GCP Deployment

Vikat Enterprise images for GCP customers are distributed through GCP Artifact Registry, enabling native Workload Identity for secure, keyless authentication.

Architecture

Prerequisites

GKE cluster (v1.24+) with Workload Identity enabled
gcloud CLI configured with appropriate permissions
kubectl configured for your GKE cluster
Your GCP project allowlisted by Vikat team

Contact the Vikat team with your GCP project ID and service account email to get access configured.

Workload Identity (Recommended)

Workload Identity provides the most secure authentication method for GKE deployments by eliminating the need for service account keys.

Step 1: Enable Workload Identity on GKE

If not already enabled, enable Workload Identity on your cluster:

# For existing cluster
gcloud container clusters update YOUR_CLUSTER_NAME \
  --region=YOUR_REGION \
  --workload-pool=YOUR_PROJECT_ID.svc.id.goog

# Verify Workload Identity is enabled
gcloud container clusters describe YOUR_CLUSTER_NAME \
  --region=YOUR_REGION \
  --format="value(workloadIdentityConfig.workloadPool)"

Step 2: Create GCP Service Account

Create a service account that will be used to pull images:

# Create service account
gcloud iam service-accounts create vikat-pull-sa \
  --display-name="Vikat Image Pull SA" \
  --project=YOUR_PROJECT_ID

Step 3: Request Access from Vikat Team

Provide the following to the Vikat team:

Your GCP project ID
Service account email: vikat-pull-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

The Vikat team will grant the necessary permissions to pull images from the registry.

Step 4: Create Namespace and ServiceAccount

kubectl create namespace vikat

apiVersion: v1
kind: ServiceAccount
metadata:
  name: vikat-sa
  namespace: vikat
  annotations:
    iam.gke.io/gcp-service-account: vikat-pull-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

Step 5: Bind Kubernetes SA to GCP SA

Allow the Kubernetes ServiceAccount to impersonate the GCP Service Account:

gcloud iam service-accounts add-iam-policy-binding \
  vikat-pull-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/iam.workloadIdentityUser \
  --member="serviceAccount:YOUR_PROJECT_ID.svc.id.goog[vikat/vikat-sa]"

Step 6: Create Image Pull Secret with Token Refresh

Artifact Registry tokens expire after 60 minutes. Use a CronJob to refresh the imagePullSecret:

apiVersion: batch/v1
kind: CronJob
metadata:
  name: refresh-ar-secret
  namespace: vikat
spec:
  schedule: "*/30 * * * *"  # Every 30 minutes
  successfulJobsHistoryLimit: 1
  failedJobsHistoryLimit: 3
  jobTemplate:
    spec:
      template:
        spec:
          serviceAccountName: vikat-sa
          containers:
          - name: token-refresh
            image: google/cloud-sdk:slim
            command: ["/bin/bash", "-c"]
            args:
            - |
              set -e
              
              # Get access token using Workload Identity
              TOKEN=$(gcloud auth print-access-token)
              
              # Delete existing secret if it exists
              kubectl delete secret ar-pull-secret --ignore-not-found -n vikat
              
              # Create new imagePullSecret
              kubectl create secret docker-registry ar-pull-secret \
                --docker-server=REGION-docker.pkg.dev \
                --docker-username=oauth2accesstoken \
                --docker-password="$TOKEN" \
                -n vikat
              
              echo "Secret refreshed at $(date)"
          restartPolicy: OnFailure
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: secret-manager
  namespace: vikat
rules:
- apiGroups: [""]
  resources: ["secrets"]
  verbs: ["get", "create", "delete"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: secret-manager-binding
  namespace: vikat
subjects:
- kind: ServiceAccount
  name: vikat-sa
  namespace: vikat
roleRef:
  kind: Role
  name: secret-manager
  apiGroup: rbac.authorization.k8s.io

Replace REGION with your Artifact Registry region (e.g., us-central1).

Step 7: Deploy Vikat

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vikat
  namespace: vikat
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vikat
  template:
    metadata:
      labels:
        app: vikat
    spec:
      serviceAccountName: vikat-sa
      imagePullSecrets:
      - name: ar-pull-secret
      containers:
      - name: vikat
        image: REGION-docker.pkg.dev/VIKAT_PROJECT/YOUR_HUB_SLUG/vikat:latest
        ports:
        - containerPort: 8080
          name: http
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "1000m"
            memory: "2Gi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 30
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 5
        volumeMounts:
        - name: config
          mountPath: /data/config.json
          subPath: config.json
      volumes:
      - name: config
        secret:
          secretName: vikat-config
---
apiVersion: v1
kind: Service
metadata:
  name: vikat
  namespace: vikat
spec:
  selector:
    app: vikat
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
  type: ClusterIP

Bootstrap: Initial Secret Creation

Before the first deployment, manually create the initial imagePullSecret:

# Authenticate gcloud
gcloud auth login

# Create initial secret
kubectl create secret docker-registry ar-pull-secret \
  --docker-server=REGION-docker.pkg.dev \
  --docker-username=oauth2accesstoken \
  --docker-password="$(gcloud auth print-access-token)" \
  -n vikat

Service Account Impersonation

For cross-project deployments or when you need to use an existing service account:

Configure Impersonation

# Grant impersonation permission
gcloud iam service-accounts add-iam-policy-binding \
  VIKAT_PROVIDED_SA@VIKAT_PROJECT.iam.gserviceaccount.com \
  --role=roles/iam.serviceAccountTokenCreator \
  --member="serviceAccount:vikat-pull-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com"

Token Refresh with Impersonation

Update the CronJob to use impersonation:

args:
- |
  set -e
  
  # Get access token by impersonating the Vikat SA
  TOKEN=$(gcloud auth print-access-token \
    --impersonate-service-account=VIKAT_PROVIDED_SA@VIKAT_PROJECT.iam.gserviceaccount.com)
  
  kubectl delete secret ar-pull-secret --ignore-not-found -n vikat
  kubectl create secret docker-registry ar-pull-secret \
    --docker-server=REGION-docker.pkg.dev \
    --docker-username=oauth2accesstoken \
    --docker-password="$TOKEN" \
    -n vikat

Service Account Key (Legacy)

Service account keys are not recommended for production. Use Workload Identity instead.

For environments that cannot use Workload Identity:

# Create key (provided by Vikat team)
# Store key securely

# Create imagePullSecret
kubectl create secret docker-registry ar-pull-secret \
  --docker-server=REGION-docker.pkg.dev \
  --docker-username=_json_key \
  --docker-password="$(cat sa-key.json)" \
  -n vikat

Verifying Access

Test Artifact Registry Authentication

# Configure docker for Artifact Registry
gcloud auth configure-docker REGION-docker.pkg.dev

# Pull test (requires impersonation or direct access)
docker pull REGION-docker.pkg.dev/VIKAT_PROJECT/YOUR_HUB_SLUG/vikat:latest

Verify Workload Identity Configuration

# Check ServiceAccount annotation
kubectl get sa vikat-sa -n vikat -o yaml

# Verify pod can authenticate
kubectl exec -it deployment/vikat -n vikat -- \
  gcloud auth print-access-token

# Check token refresh CronJob
kubectl get cronjob refresh-ar-secret -n vikat
kubectl get jobs -n vikat

Troubleshooting

ImagePullBackOff Errors

Check imagePullSecret exists: kubectl get secret ar-pull-secret -n vikat
Verify token is valid: Check if CronJob ran successfully
Check Workload Identity binding: Ensure GCP SA is bound to K8s SA

# Check pod events
kubectl describe pod -l app=vikat -n vikat

# Manually refresh token
kubectl create job --from=cronjob/refresh-ar-secret manual-refresh -n vikat

Workload Identity Issues

# Verify Workload Identity pool
gcloud container clusters describe YOUR_CLUSTER_NAME \
  --region=YOUR_REGION \
  --format="value(workloadIdentityConfig.workloadPool)"

# Check IAM binding
gcloud iam service-accounts get-iam-policy \
  vikat-pull-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com

Token Expiration

If pods fail to pull images after 60 minutes:

Verify CronJob is running: kubectl get cronjob -n vikat
Check CronJob logs: kubectl logs -l job-name=refresh-ar-secret -n vikat
Manually trigger refresh: kubectl create job --from=cronjob/refresh-ar-secret manual-refresh -n vikat

Next Steps

Configure Vikat settings for your use case
Set up observability for monitoring
Enable clustering for high availability

Platform specific guides

Config as Code

Enterprise Deployment

Common setup instructions

GCP Deployment

Architecture

Prerequisites

Workload Identity (Recommended)

Step 1: Enable Workload Identity on GKE

Step 2: Create GCP Service Account

Step 3: Request Access from Vikat Team

Step 4: Create Namespace and ServiceAccount

Step 5: Bind Kubernetes SA to GCP SA

Step 6: Create Image Pull Secret with Token Refresh

Step 7: Deploy Vikat

Bootstrap: Initial Secret Creation

Service Account Impersonation

Configure Impersonation

Token Refresh with Impersonation

Service Account Key (Legacy)

Verifying Access

Test Artifact Registry Authentication

Verify Workload Identity Configuration

Troubleshooting

ImagePullBackOff Errors

Workload Identity Issues

Token Expiration

Next Steps

​Architecture

​Prerequisites

​Workload Identity (Recommended)

​Step 1: Enable Workload Identity on GKE

​Step 2: Create GCP Service Account

​Step 3: Request Access from Vikat Team

​Step 4: Create Namespace and ServiceAccount

​Step 5: Bind Kubernetes SA to GCP SA

​Step 6: Create Image Pull Secret with Token Refresh

​Step 7: Deploy Vikat

​Bootstrap: Initial Secret Creation

​Service Account Impersonation

​Configure Impersonation

​Token Refresh with Impersonation

​Service Account Key (Legacy)

​Verifying Access

​Test Artifact Registry Authentication

​Verify Workload Identity Configuration

​Troubleshooting

​ImagePullBackOff Errors

​Workload Identity Issues

​Token Expiration

​Next Steps

Architecture

Prerequisites

Workload Identity (Recommended)

Step 1: Enable Workload Identity on GKE

Step 2: Create GCP Service Account

Step 3: Request Access from Vikat Team

Step 4: Create Namespace and ServiceAccount

Step 5: Bind Kubernetes SA to GCP SA

Step 6: Create Image Pull Secret with Token Refresh

Step 7: Deploy Vikat

Bootstrap: Initial Secret Creation

Service Account Impersonation

Configure Impersonation

Token Refresh with Impersonation

Service Account Key (Legacy)

Verifying Access

Test Artifact Registry Authentication

Verify Workload Identity Configuration

Troubleshooting

ImagePullBackOff Errors

Workload Identity Issues

Token Expiration

Next Steps