venafi-integration-core 2.1.0 → 2.2.0

package/README.md

@@ -25,30 +25,16 @@ Use this with Claude Code or any MCP-compatible AI assistant to get expert guida
 
 ### Quick Install (Claude Code CLI)
 
-```bash
-# Add to your project
-claude mcp add venafi-integration-core -- npx -y venafi-integration-core
-
-# Or add for all projects (user-level)
-claude mcp add -s user venafi-integration-core -- npx -y venafi-integration-core
-```
-
-Then add the sibling MCPs for your integration type:
+Install the core plus the MCPs for your integration type:
 
 ```bash
+claude mcp add venafi-integration-core -- npx -y venafi-integration-core     # Required for all types
 claude mcp add venafi-connector-machine -- npx -y venafi-connector-machine   # Machine connector
 claude mcp add venafi-connector-ca -- npx -y venafi-connector-ca             # CA connector
 claude mcp add venafi-adaptable-app -- npx -y venafi-adaptable-app           # Adaptable driver
 ```
 
-**Add everything** (copy-paste to install the full suite):
-
-```bash
-claude mcp add venafi-integration-core -- npx -y venafi-integration-core
-claude mcp add venafi-connector-machine -- npx -y venafi-connector-machine
-claude mcp add venafi-connector-ca -- npx -y venafi-connector-ca
-claude mcp add venafi-adaptable-app -- npx -y venafi-adaptable-app
-```
+To install user-level (available across all projects), add `-s user` after `mcp add`.
 
 ### Manual Setup
 
@@ -60,6 +46,18 @@ Add to your project's `.claude/settings.json`:
     "venafi-integration-core": {
       "command": "npx",
       "args": ["-y", "venafi-integration-core"]
+    },
+    "venafi-connector-machine": {
+      "command": "npx",
+      "args": ["-y", "venafi-connector-machine"]
+    },
+    "venafi-connector-ca": {
+      "command": "npx",
+      "args": ["-y", "venafi-connector-ca"]
+    },
+    "venafi-adaptable-app": {
+      "command": "npx",
+      "args": ["-y", "venafi-adaptable-app"]
     }
   }
 }

package/bundle.mjs

@@ -32400,11 +32400,308 @@ Save frequently -- sessions aren't persisted.`;
 - Verify error messages are helpful and descriptive
 - Test with invalid credentials, unreachable hosts, etc.
 
+---
+
 ## vSatellite Testing
-- Deploy to vSatellite and test via Venafi UI
-- Monitor logs: kubectl logs <pod-name> -n <namespace>
-- Verify Test Connection, then primary workflows
-- Test with different configurations and edge cases`;
+
+Deploying to a vSatellite is the only way to fully test the connector end-to-end. This section covers the complete workflow including container registry setup, deployment, log capture, and debugging.
+
+### Container Registry for Testing
+
+**Recommended: Public container registry (no auth required)**
+
+The simplest approach is a **public** container registry. This avoids auth token management entirely \u2014 the vSatellite can pull images without any credentials or registries.yaml changes.
+
+**AWS ECR Public** (\`public.ecr.aws\`) is a good option:
+- Free for public repositories
+- No pull authentication required (anyone can pull)
+- Push requires AWS credentials (your dev machine only)
+- No expiring tokens to manage on the vSatellite
+
+\`\`\`bash
+# One-time setup: create a public ECR repository
+aws ecr-public create-repository --repository-name tls-protect-my-connector --region us-east-1
+
+# Authenticate Docker for push (dev machine only)
+aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
+
+# Build and push
+export CONTAINER_REGISTRY=public.ecr.aws/<your-alias>
+make push
+\`\`\`
+
+Other public registry options: Docker Hub (public repos), GitHub Container Registry (public packages), Quay.io.
+
+**If you must use a private registry**: You'll need to configure \`/etc/rancher/k3s/registries.yaml\` on the vSatellite with credentials. See \`get_guidance("container-registry")\` for details. Note that some registries (AWS ECR private) use tokens that expire every 12 hours, which adds operational burden during testing.
+
+### vSatellite registries.yaml for Public ECR
+
+Even with a public registry, the vSatellite's default \`registries.yaml\` has a \`"*"\` catch-all mirror that routes ALL image pulls through \`registry.venafi.cloud\`. Your custom image doesn't exist there, so pulls fail silently.
+
+**You must add an explicit entry for \`public.ecr.aws\`:**
+
+\`\`\`yaml
+# /etc/rancher/k3s/registries.yaml
+mirrors:
+  "public.ecr.aws":
+    endpoint:
+      - "https://public.ecr.aws"            # YOUR images pull directly (first)
+      - "https://registry.venafi.cloud"     # Venafi platform images (fallback)
+    rewrite:
+      "^knative/(.*)": "public/venafi-vsatellite/knative/$1"
+      "^venafi-vsatellite/(.*)": "public/venafi-vsatellite/$1"
+      "^(.*)": "$1"  # passthrough for all other images \u2014 REQUIRED for k3s to generate certs.d entry
+  # ... keep existing docker.io and "*" entries unchanged
+\`\`\`
+
+**Key points:**
+- \`https://public.ecr.aws\` must be the **first** endpoint \u2014 k3s tries endpoints in order
+- The passthrough rewrite \`"^(.*)": "$1"\` is required \u2014 without it, k3s v1.30+ doesn't create \`certs.d/public.ecr.aws/hosts.toml\` and the \`*\` catch-all catches everything
+- Keep the Venafi rewrite rules so platform images (knative, satellite) still route correctly
+- After editing: \`sudo systemctl restart k3s\`
+- Then restart the satellite pod: \`kubectl rollout restart deployment/satellite -n satellite\`
+
+### Deployment Workflow for Testing
+
+\`\`\`bash
+# 1. Build and push container image
+export CONTAINER_REGISTRY=public.ecr.aws/<your-alias>
+make push
+
+# 2. Generate deployment manifests (injects image digest)
+make manifests
+
+# 3a. First time \u2014 register the connector
+curl -X POST "https://api.venafi.cloud/v1/plugins" \\
+  -H "tppl-api-key: <your-api-key>" \\
+  -H "Content-Type: application/json" \\
+  -d @manifest.create.json
+
+# 3b. Updates \u2014 PATCH the manifest (MUST use manifest.update.json, not raw manifest.json)
+curl -X PATCH "https://api.venafi.cloud/v1/plugins/<plugin-id>" \\
+  -H "tppl-api-key: <your-api-key>" \\
+  -H "Content-Type: application/json" \\
+  -d @manifest.update.json
+
+# 4. Click "Test Connection" in the Venafi UI to trigger deployment
+#    The platform sends req.plugin.deploy to the satellite only on user action.
+#    PATCHing the manifest alone does NOT deploy \u2014 a UI action is required.
+\`\`\`
+
+**Important**: The platform compares the stored \`deployment.image\` string to decide whether to redeploy. Pushing to the same \`:latest\` tag and PATCHing with the same URL does nothing. Use \`make manifests\` which injects the build digest, or use versioned tags (\`:v0.1.0\`, \`:v0.2.0\`).
+
+### Namespaces on the vSatellite
+
+| Namespace | What runs there | How to access logs |
+|---|---|---|
+| \`plugins\` | Connector pods (your code) | \`kubectl logs <pod> -n plugins -c user-container\` |
+| \`satellite\` | Satellite agent (orchestration) | \`kubectl logs <pod> -n satellite\` |
+| \`venafi\` | Other vSatellite system components | Rarely needed for connector debugging |
+
+### Capturing Logs from Connector Pods
+
+Connector pods are **ephemeral** \u2014 Knative scales them to zero after ~60 seconds of inactivity. This makes log capture challenging. Here are three approaches:
+
+#### Approach 1: Follow logs in real-time (simplest)
+
+Trigger an action in the Venafi UI (Test Connection, Discovery, etc.) and immediately watch for the pod:
+
+\`\`\`bash
+# Watch for pods to appear
+kubectl get pods -n plugins -w
+
+# As soon as a pod appears, grab logs (the -f flag follows in real-time)
+kubectl logs -f <pod-name> -n plugins -c user-container
+
+# Or combine: wait for any pod and stream logs
+kubectl get pods -n plugins -w | while read line; do
+  pod=$(echo "$line" | awk '{print $1}')
+  status=$(echo "$line" | awk '{print $3}')
+  if [ "$status" = "Running" ]; then
+    echo "=== Capturing logs from $pod ==="
+    kubectl logs -f "$pod" -n plugins -c user-container
+    break
+  fi
+done
+\`\`\`
+
+#### Approach 2: Disable scale-to-zero for testing
+
+Add a \`minScale\` annotation to the Knative service so pods stay running between requests:
+
+\`\`\`bash
+# Find the ksvc name
+kubectl get ksvc -n plugins
+
+# Patch it to keep at least 1 pod running
+kubectl annotate ksvc <service-name> -n plugins \\
+  autoscaling.knative.dev/min-scale="1" --overwrite
+
+# Verify the pod stays running
+kubectl get pods -n plugins -w
+\`\`\`
+
+This keeps the pod alive so you can \`kubectl logs\` and \`kubectl exec\` at your leisure.
+
+**Remember to re-enable scale-to-zero when done** (or just delete the ksvc \u2014 next deployment recreates it):
+
+\`\`\`bash
+# Remove the annotation to restore scale-to-zero behavior
+kubectl annotate ksvc <service-name> -n plugins \\
+  autoscaling.knative.dev/min-scale- --overwrite
+
+# Or delete the ksvc entirely (clean slate for next deploy)
+kubectl delete ksvc <service-name> -n plugins
+\`\`\`
+
+#### Approach 3: Deploy a log collector pod
+
+For persistent log capture across multiple test runs, deploy a sidecar-style pod that tails all connector logs:
+
+\`\`\`bash
+# Deploy a long-running pod that captures logs from all connector pods
+kubectl run log-collector -n plugins --image=bitnami/kubectl:latest --restart=Always -- \\
+  sh -c 'while true; do
+    for pod in $(kubectl get pods -n plugins -l serving.knative.dev/service -o name 2>/dev/null); do
+      kubectl logs "$pod" -c user-container --since=10s 2>/dev/null
+    done
+    sleep 5
+  done'
+
+# Read collected output
+kubectl logs log-collector -n plugins -f
+
+# Clean up when done
+kubectl delete pod log-collector -n plugins
+\`\`\`
+
+Alternatively, use \`stern\` (a multi-pod log tailer) if available:
+
+\`\`\`bash
+# Install stern: brew install stern (macOS) or go install github.com/stern/stern@latest
+# Tail all pods in the plugins namespace
+stern -n plugins -c user-container '.*'
+\`\`\`
+
+### Satellite Agent Logs
+
+The satellite agent logs contain connector invocation events, deploy commands, and error reporting. These are essential when connector pods aren't being created or when discovery completes but results aren't appearing.
+
+\`\`\`bash
+# Find the satellite pod
+kubectl get pods -n satellite
+
+# Stream satellite logs
+kubectl logs -f <satellite-pod> -n satellite
+
+# Key log patterns to watch for:
+# "processing WebSocket command","command":"req.plugin.invokeWebhook"  \u2192 webhook triggered
+# "processing WebSocket command","command":"req.plugin.deploy"         \u2192 deployment triggered
+# "Credential GetAccessToken: new way"                                 \u2192 satellite reporting results to TLSPC
+# "error waiting for service to be ready" + "error reply"              \u2192 pod failed to start
+# "encryption key secret invalid content"                              \u2192 stale secret blocking deploy
+\`\`\`
+
+**Key diagnostic**: If the satellite gets an access token after a discovery run but machine identities never appear in the UI, the connector response was accepted by the satellite but rejected by the platform. Check \`GET /v1/machines/{id}/discovery\` for \`errorCount > 0\`.
+
+### Debugging Discovery Results via API
+
+\`discoveryStatus: COMPLETED\` does NOT mean certificates were stored. It only means the workflow finished. The platform silently rejects malformed certificates.
+
+\`\`\`bash
+# Check discovery results
+curl -s "https://api.venafi.cloud/v1/machines/{machineId}/discovery" \\
+  -H "tppl-api-key: <key>" | jq .
+
+# Good result:
+# {"certificatesCountTotal": 5, "machineIdentitiesCount": 5, "errorCount": 0}
+
+# Bad result (connector response format issue):
+# {"certificatesCountTotal": 0, "machineIdentitiesCount": 0, "errorCount": 5}
+# errorCount > 0 means the platform rejected the discovery response content
+
+# Check activity logs for specific error messages:
+curl -s -X POST "https://api.venafi.cloud/v1/activitylogsearch" \\
+  -H "tppl-api-key: <key>" \\
+  -H "Content-Type: application/json" \\
+  -d '{"expression":{"operands":[{"field":"activityType","operator":"MATCH","value":"Discovery"}]},"ordering":{"orders":[{"direction":"DESC","field":"activityDate"}]},"paging":{"pageNumber":0,"pageSize":10}}' | jq .
+\`\`\`
+
+### Troubleshooting: Pod Won't Start
+
+\`\`\`bash
+# Check pod status and events
+kubectl get pods -n plugins
+kubectl describe pod <pod-name> -n plugins
+
+# ImagePullBackOff \u2014 verify the image can be pulled
+sudo crictl pull <image-url>
+
+# If crictl pull fails with redirect/HTML content, clear the cache
+sudo crictl rmi "<image-url>" 2>/dev/null
+sudo ctr -n k8s.io images rm "<image-url>" 2>/dev/null
+
+# ProgressDeadlineExceeded \u2014 Knative revision failed permanently
+# Recovery: delete the stuck ksvc and retry
+kubectl delete ksvc <service-name> -n plugins
+# Then click Test Connection in UI to trigger fresh deployment
+
+# CrashLoopBackOff \u2014 check previous container logs
+kubectl logs <pod-name> -n plugins -c user-container --previous
+\`\`\`
+
+### Troubleshooting: Satellite Not Deploying
+
+If Test Connection fails but no connector pods appear:
+
+\`\`\`bash
+# 1. Check satellite pod is running
+kubectl get pods -n satellite
+
+# 2. Check satellite logs for errors
+kubectl logs <satellite-pod> -n satellite | tail -50
+
+# 3. Restart satellite if WebSocket is stale (common after k3s restart)
+kubectl rollout restart deployment/satellite -n satellite
+
+# 4. Check for stale secrets blocking deployment
+kubectl get secrets -n plugins
+# Delete any stale secret for your connector
+kubectl delete secret <connector-slug> -n plugins
+
+# 5. Verify registries.yaml is correct and k3s has been restarted
+cat /etc/rancher/k3s/registries.yaml
+\`\`\`
+
+### Iterating During Development
+
+The typical edit-build-test cycle during vSatellite testing:
+
+\`\`\`bash
+# 1. Make code changes
+
+# 2. Build and push (single command)
+make push
+
+# 3. Generate updated manifests
+make manifests
+
+# 4. PATCH the plugin
+curl -X PATCH "https://api.venafi.cloud/v1/plugins/<id>" \\
+  -H "tppl-api-key: <key>" \\
+  -H "Content-Type: application/json" \\
+  -d @manifest.update.json
+
+# 5. (Optional) Delete existing pods to force fresh pull
+kubectl delete pods -n plugins --all
+
+# 6. Click Test Connection / run Discovery in the UI
+
+# 7. Watch logs
+kubectl logs -f <new-pod> -n plugins -c user-container
+\`\`\`
+
+**Tip**: If you set \`minScale=1\` (Approach 2 above), you may need to delete the running pod after each push to force it to pull the new image. The running pod continues using the old image until it's terminated.`;
   },
   deployment: () => DEPLOYMENT,
   troubleshooting: () => DEPLOYMENT,
@@ -32651,9 +32948,109 @@ the correct wrapper via \`jq '{manifest: .}'\`. Never manually construct the PAT
 The vSatellite uses k3s (lightweight Kubernetes) to run connector pods. Image pulls go through
 k3s's containerd runtime, which is configured via \`/etc/rancher/k3s/registries.yaml\`.
 
-**You need SSH or console access to the vSatellite host** to configure registry auth and verify pulls.
+**You need SSH or console access to the vSatellite host** to configure the registry mirror entry.
+
+## Recommended: Public Container Registry (No Auth Required)
+
+The simplest and most reliable approach is a **public** container registry. This eliminates auth token management entirely \u2014 the vSatellite can pull images without credentials.
+
+### AWS ECR Public (\`public.ecr.aws\`) \u2014 Recommended
+
+- **Free** for public repositories
+- **No pull authentication** required \u2014 anyone can pull
+- **Push** requires AWS credentials (dev machine only, not the vSatellite)
+- **No expiring tokens** to manage on the vSatellite
 
-### Pre-Flight Checklist
+\`\`\`bash
+# One-time: create a public ECR repository (requires AWS CLI + account)
+aws ecr-public create-repository --repository-name tls-protect-my-connector --region us-east-1
+
+# Authenticate Docker for pushing (dev machine only)
+aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws
+
+# Build and push
+export CONTAINER_REGISTRY=public.ecr.aws/<your-alias>
+make push
+\`\`\`
+
+### Other Public Registry Options
+
+| Registry | Setup | Notes |
+|---|---|---|
+| Docker Hub | Create public repo at hub.docker.com | Free, widely supported |
+| GitHub Container Registry | \`ghcr.io/<user>\` with public packages | Free with GitHub account |
+| Quay.io | Create public repo at quay.io | Red Hat hosted |
+
+### Private Registry Options (When Public Isn't Possible)
+
+If you must use a private registry, you'll need to configure \`/etc/rancher/k3s/registries.yaml\` with credentials. Be aware of token expiry:
+
+| Registry | Token Lifetime | Notes |
+|---|---|---|
+| Docker Hub | Long-lived (PAT) | Simplest private option |
+| GitHub Container Registry | Long-lived (PAT) | Use \`read:packages\` scope |
+| AWS ECR (private) | **12 hours** | Requires frequent refresh \u2014 adds operational burden |
+| Azure ACR | Configurable | Service principal recommended |
+| JFrog Artifactory | API key/token | Enterprise option |
+
+## vSatellite registries.yaml Configuration
+
+### For Public ECR (Recommended)
+
+Even with a public registry, the vSatellite's default \`registries.yaml\` has a \`"*"\` catch-all mirror that routes ALL image pulls through \`registry.venafi.cloud\`. Your custom image doesn't exist there, so pulls fail silently.
+
+**Add an explicit entry for \`public.ecr.aws\`:**
+
+\`\`\`yaml
+# /etc/rancher/k3s/registries.yaml
+mirrors:
+  "public.ecr.aws":
+    endpoint:
+      - "https://public.ecr.aws"            # YOUR images pull directly (first)
+      - "https://registry.venafi.cloud"     # Venafi platform images (fallback)
+    rewrite:
+      "^knative/(.*)": "public/venafi-vsatellite/knative/$1"
+      "^venafi-vsatellite/(.*)": "public/venafi-vsatellite/$1"
+      "^(.*)": "$1"  # passthrough \u2014 REQUIRED for k3s to generate certs.d entry
+  # ... keep existing docker.io and "*" entries unchanged
+\`\`\`
+
+**Key details:**
+- \`https://public.ecr.aws\` must be **first** \u2014 k3s tries endpoints in order
+- The passthrough rewrite \`"^(.*)": "$1"\` is required \u2014 without it, k3s v1.30+ doesn't create \`certs.d/public.ecr.aws/hosts.toml\` and the \`*\` catch-all catches everything
+- Keep the Venafi rewrite rules so platform images (knative, satellite) still route correctly
+- No \`configs\` section needed for public registries
+
+### For Private Registries
+
+Your registry must appear under BOTH \`mirrors\` and \`configs\`:
+
+\`\`\`yaml
+mirrors:
+  "your-registry.example.com":
+    endpoint:
+      - "https://your-registry.example.com"
+configs:
+  "your-registry.example.com":
+    auth:
+      username: <your-username>
+      password: <your-password-or-token>
+\`\`\`
+
+### After Any registries.yaml Change
+
+\`\`\`bash
+# Restart k3s to pick up new config
+sudo systemctl restart k3s
+
+# Restart satellite pod (k3s restart breaks WebSocket)
+kubectl rollout restart deployment/satellite -n satellite
+
+# Verify pull works
+sudo crictl pull <your-image-url>
+\`\`\`
+
+## Pre-Flight Checklist
 
 Before your first \`make push\`, verify these items:
 
@@ -32661,19 +33058,18 @@ Before your first \`make push\`, verify these items:
    - Without this, Docker Buildx wraps images in manifest lists that break containerd
    - The MCP Makefile template includes this by default
 
-2. **Registry auth is configured on the vSatellite**
+2. **Registry mirror is configured on the vSatellite**
    - SSH into the vSatellite and check: \`cat /etc/rancher/k3s/registries.yaml\`
-   - Your registry must appear under BOTH \`mirrors\` and \`configs\`
-   - Do NOT rely on the \`"*"\` catch-all mirror -- it routes to registry.venafi.cloud and causes digest mismatches
+   - Your registry must have an explicit mirror entry (not relying on \`*\` catch-all)
+   - For private registries: credentials must be in the \`configs\` section
 
-3. **Auth tokens are not expired** (if your registry uses short-lived tokens)
-   - Some registries (e.g., AWS ECR) use tokens that expire after hours
-   - Others (Docker Hub, GHCR) use long-lived credentials that rarely expire
-   - Check your registry's documentation for token lifetime
+3. **Auth tokens are not expired** (private registries only)
+   - AWS ECR private tokens expire every 12 hours \u2014 avoid if possible
+   - Public registries don't need tokens
 
-### Acceptance Test: Verify Pull Works
+## Acceptance Tests
 
-The single most important test before deploying a connector:
+### Test 1: Verify Pull Works (Most Important)
 
 \`\`\`bash
 # SSH into the vSatellite, then:
@@ -32682,7 +33078,7 @@ sudo crictl pull <registry>/<repo>:<tag>
 
 If this fails, the pod WILL fail with ImagePullBackOff. Fix registry access first.
 
-### Acceptance Test: Verify Image Format
+### Test 2: Verify Image Format
 
 \`\`\`bash
 # On your dev machine:
@@ -32691,7 +33087,7 @@ docker buildx imagetools inspect <registry>/<repo>:<tag>
 # Bad: manifest list with multiple entries (attestation/provenance present)
 \`\`\`
 
-### Common Failures
+## Common Failures
 
 | Symptom | Cause | Fix |
 |---|---|---|
@@ -32700,24 +33096,10 @@ docker buildx imagetools inspect <registry>/<repo>:<tag>
 | \`manifest unknown\` | Tag doesn't exist in registry | Verify with \`docker manifest inspect\` |
 | Pod stuck in ImagePullBackOff | Any of the above | Check \`kubectl describe pod\` events |
 | Pull routed to wrong endpoint | Missing explicit mirror entry | Add your registry to \`mirrors\` in registries.yaml |
+| Pull works via crictl but pod fails | Stale cached content | Clear: \`sudo crictl rmi <image>; sudo ctr -n k8s.io images rm <image>\` |
 
-### registries.yaml Format
-
-\`\`\`yaml
-mirrors:
-  "your-registry.example.com":
-    endpoint:
-      - "https://your-registry.example.com"
-configs:
-  "your-registry.example.com":
-    auth:
-      username: <your-username>
-      password: <your-password-or-token>
-\`\`\`
-
-After any change to registries.yaml: \`sudo systemctl restart k3s\`
-
-For full deployment guide including network access, build process, and troubleshooting, use: get_guidance("deployment")`;
+For full deployment guide including network access, build process, and troubleshooting, use: get_guidance("deployment")
+For vSatellite testing workflow including log capture and scale-to-zero management, use: get_guidance("testing")`;
   }
 };
 function getGuidance(args) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "venafi-integration-core",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "MCP server providing shared knowledge, templates, and tools for building Venafi integrations (connectors and adaptable drivers)",
   "main": "bundle.mjs",
   "type": "module",