Skip to main content

Plugin Engine

Overview​

This guide covers the installation of the messaging infrastructure that enables connecting MCP servers and plugins running externally to AI/Run CodeMie infrastructure.

The plugin engine consists of two components:

  • NATS - High-performance message broker enabling pub/sub and request/reply messaging patterns
  • NATS Auth Callout - Authentication service that validates NATS connections and enforces authorization policies

NATS Installation​

NATS provides the messaging backbone for CodeMie's plugin system, enabling real-time communication between the core application and distributed plugins.

Step 1: Create NATS Secrets​

Create the codemie-nats-secrets secret containing authentication credentials and encryption keys. Follow these steps to generate and encode the necessary values:

1. NATS_URL​

Internal service URL for NATS communication:

NATS_URL="nats://codemie-nats:4222"

2. Callout User Credentials​

Credentials for the NATS Auth Callout service:

# Username
CALLOUT_USERNAME="callout"

# Generate secure password
CALLOUT_PASSWORD=$(pwgen -s -1 25)

# Generate bcrypt hash (requires nats CLI installed)
CALLOUT_BCRYPTED_PASSWORD=$(nats server passwd -p "$CALLOUT_PASSWORD")

3. CodeMie User Credentials​

Credentials for CodeMie application to connect to NATS:

# Username
CODEMIE_USERNAME="codemie"

# Generate secure password
CODEMIE_PASSWORD=$(pwgen -s -1 25)

# Generate bcrypt hash (requires nats CLI installed)
CODEMIE_BCRYPTED_PASSWORD=$(nats server passwd -p "$CODEMIE_PASSWORD")

4. NATS Keys​

Generate NATS keys for JWT authentication and encrypted connections:

nsc generate nkey --account
# Output:
# ISSUER_NSEED: SAXXXXX... (private seed, keep secure)
# ISSUER_NKEY: AXXXXX... (public key)

nsc generate nkey --curve
# Output:
# ISSUER_XSEED: XSXXXXX... (private seed, keep secure)
# ISSUER_XKEY: XXXXXX... (public key)

Reference: NATS Auth Callout Example

5. Create the Secret​

Create the secret using kubectl with all generated values:

kubectl -n codemie create secret generic codemie-nats-secrets \
  --from-literal=NATS_URL="$NATS_URL" \
  --from-literal=CALLOUT_USERNAME="$CALLOUT_USERNAME" \
  --from-literal=CALLOUT_PASSWORD="$CALLOUT_PASSWORD" \
  --from-literal=CALLOUT_BCRYPTED_PASSWORD="$CALLOUT_BCRYPTED_PASSWORD" \
  --from-literal=CODEMIE_USERNAME="$CODEMIE_USERNAME" \
  --from-literal=CODEMIE_PASSWORD="$CODEMIE_PASSWORD" \
  --from-literal=CODEMIE_BCRYPTED_PASSWORD="$CODEMIE_BCRYPTED_PASSWORD" \
  --from-literal=ISSUER_NKEY="<your-nkey>" \
  --from-literal=ISSUER_NSEED="<your-nseed>" \
  --from-literal=ISSUER_XKEY="<your-xkey>" \
  --from-literal=ISSUER_XSEED="<your-xseed>" \
  --type=Opaque
Save Credentials

Save all generated passwords and keys securely. You'll need them for troubleshooting and future operations.

Alternative: YAML Secret Template

apiVersion: v1
kind: Secret
metadata:
  name: codemie-nats-secrets
  namespace: codemie
type: Opaque
data:
  NATS_URL: <base64-encoded-nats-url>
  CALLOUT_USERNAME: <base64-encoded-callout-username>
  CALLOUT_PASSWORD: <base64-encoded-callout-password>
  CALLOUT_BCRYPTED_PASSWORD: <base64-encoded-callout-bcrypted-password>
  CODEMIE_USERNAME: <base64-encoded-codemie-username>
  CODEMIE_PASSWORD: <base64-encoded-codemie-password>
  CODEMIE_BCRYPTED_PASSWORD: <base64-encoded-codemie-bcrypted-password>
  ISSUER_NKEY: <base64-encoded-issuer-nkey>
  ISSUER_NSEED: <base64-encoded-issuer-nseed>
  ISSUER_XKEY: <base64-encoded-issuer-xkey>
  ISSUER_XSEED: <base64-encoded-issuer-xseed>

To encode values: echo -n 'your-value-here' | base64

Step 2: Add NATS Helm Repository​

Add the official NATS Helm repository:

# Add repository
helm repo add nats https://nats-io.github.io/k8s/helm/charts/

# Update repository index
helm repo update nats

Step 3: Install NATS Helm Chart​

Deploy NATS using the official Helm chart:

helm upgrade --install codemie-nats nats/nats \
--version 1.2.6 \
--namespace codemie \
--values ./codemie-nats/values-aws.yaml \
--wait \
--timeout 900s

Step 4: Verify NATS Deployment​

Check that NATS is running:

# Check pod status
kubectl get pods -n codemie | grep nats

# Check NATS service
kubectl get service -n codemie codemie-nats

# Check NATS logs
kubectl logs -n codemie statefulset/codemie-nats --tail=50

Expected output:

  • NATS pods should be in Running state
  • Service should show cluster IP assigned
  • Logs should indicate successful server startup

NATS Auth Callout Installation​

NATS Auth Callout validates authentication and authorization for NATS connections to CodeMie.

Step 1: Authenticate to Container Registry​

Before deploying NATS Auth Callout, authenticate to the AI/Run CodeMie container registry:

export GOOGLE_APPLICATION_CREDENTIALS=key.json
gcloud auth application-default print-access-token | \
  helm registry login -u oauth2accesstoken --password-stdin europe-west3-docker.pkg.dev
Registry Authentication

This step is required for all AI/Run CodeMie proprietary components: codemie-ui, codemie-api, codemie-nats-auth-callout, codemie-mcp-connect-service, and mermaid-server.

If you already authenticated during the Getting Started steps, you can skip this.

Step 2: Install NATS Auth Callout Helm Chart​

Deploy the NATS Auth Callout service:

helm upgrade --install codemie-nats-auth-callout \
oci://europe-west3-docker.pkg.dev/or2-msq-epmd-edp-anthos-t1iylu/helm-charts/codemie-nats-auth-callout \
--version "x.y.z" \
--namespace codemie \
-f ./codemie-nats-auth-callout/values-aws.yaml \
--wait \
--timeout 600s

Step 3: Verify NATS Auth Callout Deployment​

Check that the auth callout service is running:

# Check pod status
kubectl get pods -n codemie | grep nats-auth-callout

# Check deployment
kubectl get deployment -n codemie codemie-nats-auth-callout

# Check logs
kubectl logs -n codemie deployment/codemie-nats-auth-callout --tail=50

Expected output:

  • Pod should be in Running state
  • Deployment should show ready replicas
  • Logs should indicate successful connection to NATS

TLS Configuration​

Choose the appropriate scenario based on your deployment architecture:

Load Balancer TLS Termination​

TLS is handled by Network Load Balancer with TLS certificate on the load balancer itself.

NATS Helm Values (codemie-nats/values-aws.yaml):

params:
  conf: |
    tls: {}
    allow_non_tls: true

CodeMie API Configuration (codemie-api/values-aws.yaml):

extraEnv:
  - name: NATS_SKIP_TLS_VERIFY
    value: "false"

NATS Auth Callout Configuration (codemie-nats-auth-callout/values-aws.yaml):

env:
  - name: SKIPTLSVERIFY
    value: "0"

Plugin URL Format:

tls://<domain>:<port>
info

The tls:// prefix forces plugins to perform TLS handshake first, which is essential because the load balancer expects TLS negotiation before any NATS protocol communication.

Post-Installation Validation​

After completing plugin engine installation, verify the following:

# NATS is running
kubectl get pods -n codemie | grep codemie-nats

# NATS Auth Callout is running
kubectl get pods -n codemie | grep nats-auth-callout

# NATS service is available
kubectl get service -n codemie codemie-nats

# NATS secrets exist
kubectl get secret codemie-nats-secrets -n codemie

# Test NATS connectivity (optional)
kubectl run -it --rm nats-test --image=natsio/nats-box:latest --restart=Never -n codemie -- nats context create test --server=nats://codemie-nats:4222

All checks should return successful results before proceeding.

Next Steps​

Once the plugin engine is configured, proceed to Core Components installation to deploy the main CodeMie application services.