Setup Wizard Skill

Setup Wizard Skill

Comprehensive knowledge for interactive setup and validation of the AWS EKS + Helm + Keycloak + Harness ecosystem.

Skill Overview

This skill provides deep expertise in:

• Multi-platform authentication and connectivity validation
• Interactive wizard flow management
• Configuration generation and repair
• Environment variable management
• Prerequisites detection and installation

AWS Setup Validation

Credentials Validation

# Validate AWS CLI credentials
aws sts get-caller-identity

# Expected output parsing
{
    "UserId": "AIDAXXXXXXXXXXXXXXXXX",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/developer"
}

# Check required permissions
aws iam simulate-principal-policy \
  --policy-source-arn "$(aws sts get-caller-identity --query Arn --output text)" \
  --action-names \
    eks:DescribeCluster \
    eks:ListClusters \
    ecr:GetAuthorizationToken \
    secretsmanager:GetSecretValue \
    secretsmanager:PutSecretValue

EKS Cluster Discovery

# List all EKS clusters in region
aws eks list-clusters --region ${AWS_REGION}

# Get cluster details
aws eks describe-cluster --name ${CLUSTER_NAME} --region ${AWS_REGION}

# Validate kubeconfig update
aws eks update-kubeconfig --name ${CLUSTER_NAME} --region ${AWS_REGION}

# Test cluster connectivity
kubectl cluster-info

ECR Validation

# Get ECR login token
aws ecr get-login-password --region ${AWS_REGION}

# List existing repositories
aws ecr describe-repositories --region ${AWS_REGION}

# Create repository if needed
aws ecr create-repository \
  --repository-name ${SERVICE_NAME} \
  --image-scanning-configuration scanOnPush=true \
  --encryption-configuration encryptionType=AES256

Secrets Manager Validation

# Test read access
aws secretsmanager get-secret-value --secret-id ${SECRET_PREFIX}test 2>&1

# Test write access (create test secret)
aws secretsmanager create-secret \
  --name "${SECRET_PREFIX}test-connectivity" \
  --secret-string "test" \
  --description "Connectivity test - safe to delete"

# Clean up test secret
aws secretsmanager delete-secret \
  --secret-id "${SECRET_PREFIX}test-connectivity" \
  --force-delete-without-recovery

Harness Setup Validation

API Connectivity

# Validate Harness API key
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/user/currentUser?accountIdentifier=${HARNESS_ACCOUNT_ID}" | jq .

# Expected response structure
{
  "status": "SUCCESS",
  "data": {
    "uuid": "xxx",
    "name": "User Name",
    "email": "user@example.com"
  }
}

Organization & Project Validation

# List organizations
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/organizations?accountIdentifier=${HARNESS_ACCOUNT_ID}" | jq .

# List projects in organization
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/projects?accountIdentifier=${HARNESS_ACCOUNT_ID}&orgIdentifier=${HARNESS_ORG_ID}" | jq .

# Validate project access
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/projects/${HARNESS_PROJECT_ID}?accountIdentifier=${HARNESS_ACCOUNT_ID}&orgIdentifier=${HARNESS_ORG_ID}" | jq .

Connector Validation

# List existing connectors
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/connectors?accountIdentifier=${HARNESS_ACCOUNT_ID}&orgIdentifier=${HARNESS_ORG_ID}&projectIdentifier=${HARNESS_PROJECT_ID}" | jq .

# Test connector connectivity
curl -sf -X POST -H "x-api-key: ${HARNESS_API_KEY}" \
  -H "Content-Type: application/json" \
  "${HARNESS_BASE_URL}/ng/api/connectors/testConnection/${CONNECTOR_ID}?accountIdentifier=${HARNESS_ACCOUNT_ID}&orgIdentifier=${HARNESS_ORG_ID}&projectIdentifier=${HARNESS_PROJECT_ID}"

Delegate Health Check

# List delegates
curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
  "${HARNESS_BASE_URL}/ng/api/delegate-setup/listDelegates?accountId=${HARNESS_ACCOUNT_ID}&orgId=${HARNESS_ORG_ID}&projectId=${HARNESS_PROJECT_ID}" | jq .

# Check delegate status
# Status should be "ENABLED" and lastHeartbeat within last 5 minutes

Creating AWS Connector

connector:
  name: aws_connector
  identifier: aws_connector
  type: Aws
  spec:
    credential:
      type: Irsa  # For IRSA-based auth
      spec:
        delegateSelector: eks-delegate
    executeOnDelegate: true
    proxy: false

Creating EKS Connector

connector:
  name: eks_dev_connector
  identifier: eks_dev_connector
  type: K8sCluster
  spec:
    credential:
      type: InheritFromDelegate
      spec:
        delegateSelectors:
          - eks-delegate-dev

Keycloak Setup Validation

Server Connectivity

# Check Keycloak is reachable
curl -sf "${KEYCLOAK_URL}/realms/master/.well-known/openid-configuration" | jq .

# Get server info (requires admin)
curl -sf "${KEYCLOAK_URL}/admin/serverinfo" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

Admin Token Retrieval

# Get admin access token
curl -sf -X POST "${KEYCLOAK_URL}/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=password" \
  -d "client_id=admin-cli" \
  -d "username=${KEYCLOAK_ADMIN}" \
  -d "password=${KEYCLOAK_ADMIN_PASSWORD}" | jq -r '.access_token'

Realm Operations

# List realms
curl -sf "${KEYCLOAK_URL}/admin/realms" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq '.[].realm'

# Create realm
curl -sf -X POST "${KEYCLOAK_URL}/admin/realms" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "realm": "production",
    "enabled": true,
    "sslRequired": "external",
    "registrationAllowed": false,
    "loginWithEmailAllowed": true,
    "duplicateEmailsAllowed": false,
    "resetPasswordAllowed": true,
    "bruteForceProtected": true
  }'

# Get realm configuration
curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq .

Client Management

# List clients in realm
curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}/clients" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq '.[].clientId'

# Create OIDC client
curl -sf -X POST "${KEYCLOAK_URL}/admin/realms/${REALM}/clients" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "my-service-client",
    "enabled": true,
    "protocol": "openid-connect",
    "publicClient": false,
    "standardFlowEnabled": true,
    "directAccessGrantsEnabled": true,
    "serviceAccountsEnabled": true,
    "authorizationServicesEnabled": false,
    "attributes": {
      "pkce.code.challenge.method": "S256"
    },
    "redirectUris": ["*"],
    "webOrigins": ["*"]
  }'

# Get client secret
CLIENT_UUID=$(curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}/clients?clientId=${CLIENT_ID}" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.[0].id')

curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}/clients/${CLIENT_UUID}/client-secret" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.value'

Test User Creation

# Create test user
curl -sf -X POST "${KEYCLOAK_URL}/admin/realms/${REALM}/users" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "enabled": true,
    "emailVerified": true,
    "email": "testuser@example.com",
    "credentials": [{
      "type": "password",
      "value": "testpass",
      "temporary": false
    }]
  }'

# Assign role to user
USER_ID=$(curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}/users?username=testuser" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.[0].id')

ROLE_ID=$(curl -sf "${KEYCLOAK_URL}/admin/realms/${REALM}/roles/${ROLE_NAME}" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" | jq -r '.id')

curl -sf -X POST "${KEYCLOAK_URL}/admin/realms/${REALM}/users/${USER_ID}/role-mappings/realm" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H "Content-Type: application/json" \
  -d "[{\"id\": \"${ROLE_ID}\", \"name\": \"${ROLE_NAME}\"}]"

Local Development Validation

Prerequisites Check

# Check Docker
docker --version && docker info > /dev/null 2>&1

# Check kubectl
kubectl version --client

# Check Helm
helm version

# Check AWS CLI
aws --version

# Check Kind
kind --version

# Check Skaffold
skaffold version

Tool Installation

# Install Kind (macOS/Linux)
curl -Lo ./kind https://kind.sigs.k8s.io/dl/v0.20.0/kind-$(uname)-amd64
chmod +x ./kind
sudo mv ./kind /usr/local/bin/kind

# Install Skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-$(uname)-amd64
chmod +x skaffold
sudo mv skaffold /usr/local/bin/

# Install yq
sudo wget -qO /usr/local/bin/yq https://github.com/mikefarah/yq/releases/latest/download/yq_$(uname)_amd64
sudo chmod +x /usr/local/bin/yq

Local Stack Validation

# Check Kind cluster
kind get clusters

# Check LocalStack
curl -sf http://localhost:4566/_localstack/health | jq .

# Check local Keycloak
curl -sf http://localhost:8080/realms/master/.well-known/openid-configuration

# Check local registry
curl -sf http://localhost:5000/v2/_catalog

Configuration Generation

Project Configuration File

# .claude/eks-helm-keycloak.local.yaml
plugin:
  name: aws-eks-helm-keycloak
  version: "1.0.0"
  setupCompleted: true
  setupDate: "2024-01-15T10:30:00Z"

aws:
  region: us-west-2
  accountId: "123456789012"
  secretsPrefix: "my-app/"
  clusters:
    development: my-app-dev
    staging: my-app-staging
    production: my-app-prod

harness:
  accountId: "xxx"
  orgId: default
  projectId: eks-deployments
  codeRepo: my-app
  connectors:
    - aws_connector
    - eks_dev_connector
    - eks_staging_connector
    - eks_prod_connector
    - ecr_connector

keycloak:
  url: "https://keycloak.example.com"
  realms:
    development: development
    staging: staging
    production: production
  clientPattern: "{service}-client"

localDev:
  configured: true
  ports:
    app: 3000
    keycloak: 8080
    localstack: 4566
    registry: 5000

Environment File Generation

# .env.eks-setup
# AWS Configuration
AWS_REGION=us-west-2
AWS_ACCOUNT_ID=123456789012
EKS_CLUSTER_DEV=my-app-dev
EKS_CLUSTER_STAGING=my-app-staging
EKS_CLUSTER_PROD=my-app-prod

# Harness Configuration
HARNESS_ACCOUNT_ID=xxx
HARNESS_ORG_ID=default
HARNESS_PROJECT_ID=eks-deployments
# HARNESS_API_KEY stored in secrets manager

# Keycloak Configuration
KEYCLOAK_URL=https://keycloak.example.com
KEYCLOAK_REALM_DEV=development
KEYCLOAK_REALM_STAGING=staging
KEYCLOAK_REALM_PROD=production
# KEYCLOAK_ADMIN_PASSWORD stored in secrets manager

# Local Development
LOCAL_KEYCLOAK_PORT=8080
LOCAL_LOCALSTACK_PORT=4566
LOCAL_REGISTRY_PORT=5000

Repair Mode Logic

Issue Detection

# Check AWS connectivity issues
aws_status() {
  aws sts get-caller-identity > /dev/null 2>&1 && echo "ok" || echo "failed"
}

# Check Harness connectivity
harness_status() {
  curl -sf -H "x-api-key: ${HARNESS_API_KEY}" \
    "${HARNESS_BASE_URL}/ng/api/user/currentUser?accountIdentifier=${HARNESS_ACCOUNT_ID}" \
    > /dev/null 2>&1 && echo "ok" || echo "failed"
}

# Check Keycloak connectivity
keycloak_status() {
  curl -sf "${KEYCLOAK_URL}/realms/master/.well-known/openid-configuration" \
    > /dev/null 2>&1 && echo "ok" || echo "failed"
}

Common Repair Actions

Issue	Detection	Repair Action
Expired AWS credentials	aws sts get-caller-identity fails	Re-authenticate with SSO or refresh tokens
Invalid Harness API key	401 from Harness API	Generate new API key in Harness UI
Keycloak unreachable	Connection timeout	Check URL, verify network, check TLS
Delegate offline	Missing heartbeat	Check delegate pod, restart if needed
Invalid kubeconfig	kubectl fails	Run aws eks update-kubeconfig
Missing connector	Connector not found	Auto-create connector

Validation Mode Output

Health Report Format

╔══════════════════════════════════════════════════════════════╗
║                    ECOSYSTEM HEALTH REPORT                    ║
╠══════════════════════════════════════════════════════════════╣
║                                                                ║
║  AWS                                        Status: ✅ Healthy ║
║  ├── Credentials                           ✅ Valid           ║
║  ├── EKS Clusters (3)                      ✅ Accessible      ║
║  ├── ECR Registry                          ✅ Connected       ║
║  └── Secrets Manager                       ✅ Accessible      ║
║                                                                ║
║  Harness                                    Status: ⚠️ Warning ║
║  ├── API Connection                        ✅ Connected       ║
║  ├── Project Access                        ✅ Authorized      ║
║  ├── Connectors (4/5)                      ⚠️ 1 Invalid       ║
║  └── Delegates (3)                         ✅ Healthy         ║
║                                                                ║
║  Keycloak                                   Status: ✅ Healthy ║
║  ├── Server                                ✅ Reachable       ║
║  ├── Admin Access                          ✅ Valid           ║
║  └── Realms (3)                            ✅ Configured      ║
║                                                                ║
║  Local Development                          Status: ⚠️ Warning ║
║  ├── Docker                                ✅ Running         ║
║  ├── Tools                                 ⚠️ Kind missing    ║
║  └── Configuration                         ✅ Present         ║
║                                                                ║
╠══════════════════════════════════════════════════════════════╣
║  Overall: ⚠️ WARNINGS FOUND                                   ║
║                                                                ║
║  Recommended Actions:                                          ║
║  1. Fix invalid connector: eks_staging_connector               ║
║  2. Install missing tool: kind                                 ║
║                                                                ║
║  Run: /eks:setup --mode=repair                                 ║
╚══════════════════════════════════════════════════════════════╝

Interactive Flow Helpers

Progress Display

Setup Progress:
  ● AWS Configuration        ← Current
  ○ Harness Platform
  ○ Keycloak Authentication
  ○ Local Development
  ○ Final Validation

[▓▓▓▓▓▓▓▓░░░░░░░░░░░░░░░░░] 20% Complete

Input Validation Patterns

// AWS Account ID
const awsAccountPattern = /^\d{12}$/;

// AWS Region
const awsRegionPattern = /^[a-z]{2}-[a-z]+-\d$/;

// Harness Account ID
const harnessAccountPattern = /^[a-zA-Z0-9_-]+$/;

// URL validation
const urlPattern = /^https?:\/\/[^\s/$.?#].[^\s]*$/;

// Realm name
const realmPattern = /^[a-z0-9-]+$/;

Error Recovery

• Graceful handling of network failures
• Retry with exponential backoff for transient errors
• Clear error messages with suggested fixes
• Option to skip and continue with partial setup
• Save progress for resume after failures