From 6c7cfcb858ac340fa957421adbd02d09cb25a178 Mon Sep 17 00:00:00 2001 From: eli Date: Fri, 9 Jan 2026 15:29:54 -0600 Subject: [PATCH 1/2] gke update and imagePullSecrets --- docs/how-to/deploy/on-prem/installation.mdx | 263 +++++++++++++++++++ docs/how-to/deploy/on-prem/prerequisites.mdx | 121 ++++++++- docs/how-to/deploy/on-prem/reference.mdx | 69 ++++- 3 files changed, 443 insertions(+), 10 deletions(-) diff --git a/docs/how-to/deploy/on-prem/installation.mdx b/docs/how-to/deploy/on-prem/installation.mdx index 373d3090..1e0ffe1c 100644 --- a/docs/how-to/deploy/on-prem/installation.mdx +++ b/docs/how-to/deploy/on-prem/installation.mdx @@ -550,6 +550,246 @@ cat ~/.ssh/id_rsa # or your specific key file +## Step 3.5: Push Images to Private Registry (GKE Example) + +
+
+
+

+ Optional: If you're deploying to Google Kubernetes Engine (GKE) and want to use Google Artifact Registry (GAR) or Google Container Registry (GCR), you can push the images to your private registry before installation. Skip this step if using Docker Hub or if images are already in your registry. +

+
+
+
+ +### Prerequisites for GKE Registry + +Before pushing images, you need to: + +1. **Create a Google Artifact Registry repository** (this is NOT done by the script): + +```bash +# Authenticate with Google Cloud +gcloud auth login + +# Set your project +gcloud config set project YOUR_PROJECT_ID + +# Create Artifact Registry repository +gcloud artifacts repositories create permit-platform \ + --repository-format=docker \ + --location=us-central1 \ + --project=YOUR_PROJECT_ID + +# Configure Docker authentication +gcloud auth configure-docker us-central1-docker.pkg.dev +``` + +2. **Verify authentication**: + +```bash +# Test that Docker can authenticate to GAR +docker pull us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform/hello-world || echo "Authentication configured" +``` + +### Push Images to Google Artifact Registry + +The installer package includes a convenience script to push all images to your GKE registry: + +```bash +# Navigate to scripts directory +cd scripts + +# Push to Google Artifact Registry (example for us-central1) +./push-images-to-registry.sh us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform +``` + +**What this script does:** + +1. Loads all ~35 images from the tar files in the `images/` directory +2. Tags each image for your target registry (preserving original version tags) +3. Pushes both the original tag and `:latest` tag to your registry +4. **Automatically updates** `charts/permit-platform/values.yaml` with your registry URL +5. Creates a timestamped backup of your original values.yaml + +**Expected output:** + +```bash +╔══════════════════════════════════════════════════════════════╗ +║ Permit Platform Image Push Script ║ +╚══════════════════════════════════════════════════════════════╝ + +Target Registry: us-central1-docker.pkg.dev/my-project/permit-platform +Images Directory: ../images + +Found 35 images to push + +[1/35] Processing permit-backend-v2.tar + Loading image from tar... + Loaded: permitio/permit-backend-v2:latest + Tagging as us-central1-docker.pkg.dev/my-project/permit-platform/permit-backend-v2:latest + Pushing... + ✓ Done + +[2/35] Processing permit-frontend.tar + ... + +╔══════════════════════════════════════════════════════════════╗ +║ All images pushed successfully! ║ +╚══════════════════════════════════════════════════════════════╝ + +Updating values.yaml with registry: us-central1-docker.pkg.dev/my-project/permit-platform +✅ Updated values.yaml with imageRegistry: "us-central1-docker.pkg.dev/my-project/permit-platform" + +Next steps: +1. Update charts/permit-platform/values.yaml with your frontend domain: + frontendDomain: "your-domain.company.com" + +2. Run the installer with --skip-images flag: + cd scripts + ./install-permit-platform.sh --gke --skip-images +``` + +**Time and storage requirements:** +- **Time**: 10-20 minutes depending on network speed +- **Bandwidth**: ~12GB upload +- **Registry storage**: ~12GB required in GAR + +### Verify Images in Registry + +After pushing, verify images are accessible: + +```bash +# List all images in your GAR repository +gcloud artifacts docker images list us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform + +# Check a specific image +gcloud artifacts docker images describe \ + us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform/permit-backend-v2:latest +``` + +### Using Other Private Registries + +While this guide focuses on GKE with Google Artifact Registry, the `push-images-to-registry.sh` script works with any Docker-compatible registry: + +- **AWS ECR**: `123456789012.dkr.ecr.us-east-1.amazonaws.com/permit-platform` +- **Azure ACR**: `myregistry.azurecr.io/permit-platform` +- **JFrog Artifactory**: `artifactory.company.com/permit-platform` +- **Harbor**: `harbor.company.com/permit-platform` + +For non-GKE registries, authenticate to your registry using the appropriate method before running the push script, and manually update the `imageRegistry` field in `charts/permit-platform/values.yaml`. + +#### Important: Registry Authentication for Kubernetes + +
+
+
+

+ ⚠️ Critical: If your private registry requires authentication (Artifactory, Harbor, private Docker registries), you MUST create a Kubernetes imagePullSecret and configure it in the Helm chart before installation. Without this, pods will fail to pull images with "ImagePullBackOff" errors. +

+
+
+
+ +**When you need imagePullSecrets:** +- ✅ **GKE with GAR/GCR**: Not needed (GKE nodes authenticate automatically via Workload Identity) +- ✅ **EKS with ECR**: Not needed (EKS nodes authenticate automatically via IAM roles) +- ✅ **AKS with ACR**: Not needed (AKS nodes authenticate automatically via managed identity) +- ❌ **JFrog Artifactory**: Required (needs username/password or token) +- ❌ **Harbor**: Required (needs username/password) +- ❌ **Private Docker registries**: Required (needs authentication) + +**How to configure imagePullSecrets:** + +1. **Create the Kubernetes secret** before installation: + +```bash +# For registries requiring username/password (Artifactory, Harbor, etc.) +kubectl create secret docker-registry registry-credentials \ + --docker-server=artifactory.company.com \ + --docker-username=YOUR_USERNAME \ + --docker-password=YOUR_PASSWORD_OR_TOKEN \ + --docker-email=your-email@company.com \ + --namespace permit-platform + +# Verify secret was created +kubectl get secret registry-credentials -n permit-platform +``` + +2. **Configure imagePullSecrets in your values.yaml** file: + +The Helm chart now supports `global.imagePullSecrets`. Add this to your `charts/permit-platform/values.yaml`: + +```yaml +global: + imageRegistry: "artifactory.company.com/permit-platform" + imagePullPolicy: "IfNotPresent" + + # Add your image pull secrets here + imagePullSecrets: + - registry-credentials +``` + +**That's it!** The Helm chart will automatically apply the imagePullSecrets to all deployments and jobs. + +**Multiple secrets example:** + +```yaml +global: + imagePullSecrets: + - registry-credentials + - backup-registry-credentials +``` + +
+
+
+

+ ✅ Simplified: As of January 2026, the Helm chart includes built-in support for global.imagePullSecrets. No manual template editing required! +

+
+
+
+ +**Alternative: Use node-level registry authentication** (if supported by your Kubernetes distribution) + +### Important: Skip Image Loading When Using Private Registry + +
+
+
+

+ Note: If you pushed images to a private registry (GKE/GAR, Artifactory, Harbor, etc.) using the push-images-to-registry.sh script, you MUST use the --skip-images flag when running the installer. This prevents the installer from trying to load images from local tar files. +

+
+
+
+ +**Correct usage when images are in your registry:** + +```bash +# After pushing images to your private registry, run installer with --skip-images +cd scripts +./install-permit-platform.sh --gke --skip-images # For GKE +./install-permit-platform.sh --skip-images # For EKS/AKS/on-prem +./install-permit-platform.sh --openshift --skip-images # For OpenShift +``` + +**When NOT to use --skip-images:** +- Installing from the tar.gz package for the first time +- Using Docker Hub public images +- Images are loaded to local Docker daemon (Kind clusters) + +
+
+
+

+ ✅ Ready: After pushing images to your registry and configuring values.yaml with imagePullSecrets, proceed to Step 4 to run the installation with --skip-images flag. +

+
+
+
+ ## Step 4: Run Installation ### Complete Installation Options Reference @@ -587,6 +827,29 @@ The installer script `./scripts/install-permit-platform.sh` provides comprehensi # - Handles OpenShift-specific networking ``` +#### Google GKE Deployment +```bash +# Deploy to Google Kubernetes Engine +./scripts/install-permit-platform.sh --gke + +# What it does: +# - Configures for GKE-specific settings +# - Handles GKE networking and storage +# - Compatible with both GKE Standard and Autopilot +# - Works with Google Artifact Registry (GAR) or GCR +# - Installs nginx-ingress-controller (if not present) +``` + +
+
+
+

+ Note: GKE deployments require nginx-ingress-controller for ingress routing. The installer will set this up if not already installed in your cluster. +

+
+
+
+ #### Local Development (Kind) ```bash # Deploy to local Kind cluster for development diff --git a/docs/how-to/deploy/on-prem/prerequisites.mdx b/docs/how-to/deploy/on-prem/prerequisites.mdx index f0f5286e..55ed9438 100644 --- a/docs/how-to/deploy/on-prem/prerequisites.mdx +++ b/docs/how-to/deploy/on-prem/prerequisites.mdx @@ -160,6 +160,115 @@ The Permit Platform is an **enterprise-grade authorization system** with signifi - **Storage**: CSI-compatible storage class with dynamic provisioning - **Network**: OpenShift SDN or OVN-Kubernetes networking +### Google GKE-Specific Requirements + +**For Google Kubernetes Engine deployments:** + +#### GKE Cluster Types + +GKE offers two cluster modes, both supported by Permit Platform: + +- **GKE Standard**: Full control over node configuration + - Recommended node type: **n1-standard-4** or **e2-standard-4** (4 vCPU, 15-16GB RAM) + - Worker nodes: 3-6 nodes for production + - Best for: Production deployments requiring full control + +- **GKE Autopilot**: Fully managed, automatic node provisioning + - Nodes: Automatically scaled based on workload + - Best for: Simplified operations, no node management + +#### GKE Prerequisites and Setup + +**1. Install Google Cloud SDK:** + +```bash +# macOS +brew install --cask google-cloud-sdk + +# Linux +curl https://sdk.cloud.google.com | bash +exec -l $SHELL + +# Verify installation +gcloud --version +``` + +**2. Authenticate and configure:** + +```bash +# Authenticate with Google Cloud +gcloud auth login + +# Set your project +gcloud config set project YOUR_PROJECT_ID + +# Get cluster credentials +gcloud container clusters get-credentials YOUR_CLUSTER_NAME \ + --zone us-central1-a \ + --project YOUR_PROJECT_ID + +# Verify cluster access +kubectl cluster-info +kubectl get nodes +``` + +**3. Container Registry Setup (Required for Private Registry):** + +If using Google Artifact Registry (recommended) or Google Container Registry: + +```bash +# Create Artifact Registry repository +gcloud artifacts repositories create permit-platform \ + --repository-format=docker \ + --location=us-central1 \ + --description="Permit Platform container images" \ + --project=YOUR_PROJECT_ID + +# Configure Docker authentication +gcloud auth configure-docker us-central1-docker.pkg.dev + +# Your registry URL will be: +# us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform +``` + +**Alternative: Google Container Registry (Legacy):** + +```bash +# Configure Docker authentication for GCR +gcloud auth configure-docker + +# Your registry URL will be: +# gcr.io/YOUR_PROJECT_ID +``` + +#### GKE IAM Permissions Required + +Your Google Cloud service account or user needs these permissions: + +- `container.clusters.get` - View cluster details +- `container.clusters.update` - Update cluster configuration +- `artifactregistry.repositories.uploadArtifacts` - Push images to GAR +- `artifactregistry.repositories.downloadArtifacts` - Pull images from GAR +- Or role: `roles/container.admin` and `roles/artifactregistry.writer` + +#### GKE Networking Requirements + +- **Ingress Controller**: Platform requires **nginx-ingress-controller** + - The installer will set this up automatically with `--gke` flag + - Creates a Google Cloud Load Balancer automatically + - External IP assigned for ingress traffic + +- **Load Balancer**: GCP Load Balancer created automatically for ingress +- **Storage**: Uses Google Persistent Disks (SSD) automatically +- **Network**: VPC-native cluster recommended for better security + +#### GKE-Specific Notes + +- **Security Contexts**: Some database containers run as root (handled automatically) +- **Storage Class**: Default `standard-rwo` or `premium-rwo` storage classes work +- **TLS**: Can use self-signed certificates or Google-managed certificates +- **Ingress**: nginx-ingress creates LoadBalancer service with external IP + ### Required Tools The installer checks for these tools and will guide you to install them if missing: @@ -167,12 +276,18 @@ The installer checks for these tools and will guide you to install them if missi #### For OpenShift Deployments - **oc**: OpenShift command-line tool (primary) - **kubectl**: Kubernetes command-line tool (also supported) -- **helm**: Helm v3.8+ package manager +- **helm**: Helm v3.8+ package manager - **docker**: Docker runtime (for loading images) -#### For Standard Kubernetes +#### For Google GKE Deployments +- **gcloud**: Google Cloud SDK (for authentication and cluster access) +- **kubectl**: Kubernetes command-line tool +- **helm**: Helm v3.8+ package manager +- **docker**: Docker runtime (for pushing images to registry) + +#### For Standard Kubernetes (EKS, AKS, on-premise) - **kubectl**: Kubernetes command-line tool -- **helm**: Helm v3.8+ package manager +- **helm**: Helm v3.8+ package manager - **docker**: Docker runtime (for loading images)
diff --git a/docs/how-to/deploy/on-prem/reference.mdx b/docs/how-to/deploy/on-prem/reference.mdx index 7dbe326f..3f275f8f 100644 --- a/docs/how-to/deploy/on-prem/reference.mdx +++ b/docs/how-to/deploy/on-prem/reference.mdx @@ -26,9 +26,12 @@ Reference materials for Permit Platform on-premise deployment. ### Deployment Targets ```bash -# Production Kubernetes (EKS, GKE, AKS, on-premise) +# Production Kubernetes (EKS, AKS, on-premise) ./scripts/install-permit-platform.sh +# Google Kubernetes Engine (GKE) +./scripts/install-permit-platform.sh --gke + # OpenShift (ROSA, OCP) ./scripts/install-permit-platform.sh --openshift @@ -58,13 +61,41 @@ Reference materials for Permit Platform on-premise deployment. # Preview without applying ./scripts/install-permit-platform.sh --dry-run -# Skip image loading (testing/re-runs) +# Skip image loading (REQUIRED when using pushed images to private registry) ./scripts/install-permit-platform.sh --skip-images # OpenShift with custom registry ./scripts/install-permit-platform.sh --openshift --skip-openshift-registry ``` +### When to Use --skip-images Flag + +**Use `--skip-images` when:** +- ✅ Images are already pushed to your private registry (GKE/GAR, Artifactory, Harbor, ECR, ACR) +- ✅ Re-running installation after initial image load +- ✅ Testing Helm chart changes without reloading images + +**Do NOT use `--skip-images` when:** +- ❌ First-time installation from tar.gz package +- ❌ Images need to be loaded to Docker daemon (Kind clusters) +- ❌ Using Docker Hub and images aren't pre-loaded + +**Example workflows:** + +```bash +# Workflow 1: GKE with Google Artifact Registry +./scripts/push-images-to-registry.sh us-central1-docker.pkg.dev/project/permit-platform +./scripts/install-permit-platform.sh --gke --skip-images + +# Workflow 2: Artifactory with imagePullSecrets +./scripts/push-images-to-registry.sh artifactory.company.com/permit-platform +kubectl create secret docker-registry registry-credentials --docker-server=artifactory.company.com ... +./scripts/install-permit-platform.sh --skip-images + +# Workflow 3: Standard K8s, first install with local tar files +./scripts/install-permit-platform.sh # NO --skip-images flag +``` + ## Kubernetes Management Commands ### Pod and Service Management @@ -183,12 +214,36 @@ global: frontendDomain: "permit.yourcompany.com" # CHANGEME_FRONTEND_DOMAIN # Image registry configuration - imageRegistry: "" # Empty for Docker Hub - # Or: "123456789.dkr.ecr.region.amazonaws.com" for ECR - # Or: "myregistry.azurecr.io" for Azure - # Or: "gcr.io/project-id" for GCP + # This field is automatically set when using push-images-to-registry.sh script + imageRegistry: "" # Empty for Docker Hub (public images) + # Or: "us-central1-docker.pkg.dev/project/repo" for Google Artifact Registry + # Or: "gcr.io/project-id" for Google Container Registry + # Or: "123456789.dkr.ecr.region.amazonaws.com/repo" for AWS ECR + # Or: "myregistry.azurecr.io/repo" for Azure ACR + # Or: "artifactory.company.com/repo" for JFrog Artifactory imagePullPolicy: "IfNotPresent" # Always, Never, IfNotPresent - + + # Note: The push-images-to-registry.sh script automatically updates this field + # when you push images to your private registry. See installation guide Step 3.5. + + # Image pull secrets for private registries (optional) + # Required for registries that need authentication (Artifactory, Harbor, private registries) + # Not needed for GKE/GAR, EKS/ECR, or AKS/ACR (automatic node authentication) + # + # IMPORTANT: You must create the Kubernetes secret BEFORE installation: + # kubectl create secret docker-registry registry-credentials \ + # --docker-server=artifactory.company.com \ + # --docker-username=USERNAME \ + # --docker-password=PASSWORD \ + # --namespace=permit-platform + # + # Then reference the secret name here: + imagePullSecrets: [] + # Example: + # imagePullSecrets: + # - registry-credentials + # - backup-registry-credentials + # Database configuration postgres: enabled: true From 0762229dda4b3a46a24647818743dc0950bd103d Mon Sep 17 00:00:00 2001 From: eli Date: Fri, 9 Jan 2026 17:54:54 -0600 Subject: [PATCH 2/2] private registry section have been added --- docs/how-to/deploy/on-prem/quick-start.mdx | 63 ++++++ .../how-to/deploy/on-prem/troubleshooting.mdx | 198 ++++++++++++++++++ 2 files changed, 261 insertions(+) diff --git a/docs/how-to/deploy/on-prem/quick-start.mdx b/docs/how-to/deploy/on-prem/quick-start.mdx index bf143824..464c0591 100644 --- a/docs/how-to/deploy/on-prem/quick-start.mdx +++ b/docs/how-to/deploy/on-prem/quick-start.mdx @@ -110,6 +110,69 @@ permitServices: ./scripts/install-permit-platform.sh --help ``` +**Using Private Container Registry? (GKE/Artifactory/Harbor)** + +
+
+
+

+ 📦 Private Registry Setup: If you're using Google GKE with Artifact Registry, JFrog Artifactory, Harbor, or another private registry, follow these additional steps before installation. +

+
+
+
+ +**Step 1: Push images to your private registry** +```bash +# Push all images to your registry (run from installer directory) +./scripts/push-images-to-registry.sh us-central1-docker.pkg.dev/project/repo # GKE/GAR +# or +./scripts/push-images-to-registry.sh artifactory.company.com/permit # Artifactory +``` + +**Step 2: Configure authentication (Artifactory/Harbor only - skip for GKE/EKS/AKS)** + +GKE, EKS, and AKS authenticate automatically. For Artifactory/Harbor: +```bash +# Create Kubernetes secret for registry authentication +kubectl create secret docker-registry registry-credentials \ + --docker-server=artifactory.company.com \ + --docker-username=YOUR_USERNAME \ + --docker-password=YOUR_TOKEN \ + --namespace=permit-platform + +# Then add to values.yaml: +# global: +# imagePullSecrets: +# - registry-credentials +``` + +**Step 3: Run installer with --skip-images flag** +```bash +# IMPORTANT: Use --skip-images since images are already in your registry! + +# For GKE: +./scripts/install-permit-platform.sh --gke --skip-images + +# For other Kubernetes with private registry: +./scripts/install-permit-platform.sh --skip-images + +# For OpenShift with private registry: +./scripts/install-permit-platform.sh --openshift --skip-images +``` + +
+
+
+

+ 💡 Important: The --skip-images flag tells the installer to skip loading images from tar files since they're already in your registry. Without this flag, the installer will try to load images from local tar files, which will cause version mismatches! +

+
+
+
+ +For complete private registry setup instructions, see [Installation Guide Step 3.5](/how-to/deploy/on-prem/installation#step-35-push-images-to-private-registry-gke-example). +
diff --git a/docs/how-to/deploy/on-prem/troubleshooting.mdx b/docs/how-to/deploy/on-prem/troubleshooting.mdx index 3fb0b28f..00dd39ab 100644 --- a/docs/how-to/deploy/on-prem/troubleshooting.mdx +++ b/docs/how-to/deploy/on-prem/troubleshooting.mdx @@ -329,6 +329,204 @@ kubectl get events -n permit-platform --sort-by='.lastTimestamp' kubectl scale deployment celery-general -n permit-platform --replicas=1 ``` +### ImagePullBackOff Errors + +
+
+
+

+ ❌ Problem: Pods stuck in ImagePullBackOff state - cannot pull container images +

+
+
+
+ +**Error symptoms:** +```bash +kubectl get pods -n permit-platform +NAME READY STATUS RESTARTS AGE +permit-backend-v2-xxx 0/1 ImagePullBackOff 0 2m +permit-frontend-xxx 0/1 ImagePullBackOff 0 2m +``` + +**Diagnostic steps:** +```bash +# Check pod events for detailed error message +kubectl describe pod permit-backend-v2-xxx -n permit-platform + +# Common error messages you'll see: +# - "Failed to pull image... unauthorized: authentication required" +# → Missing or incorrect imagePullSecrets +# +# - "Failed to pull image... not found" or "manifest unknown" +# → Images not pushed to registry, or wrong imageRegistry in values.yaml +# +# - "Failed to pull image... denied: Permission denied" +# → GKE/EKS/AKS node doesn't have permission to pull from registry +``` + +**Solutions by Root Cause:** + +**1. Missing imagePullSecrets (Artifactory/Harbor/Private Registries)** + +If using Artifactory, Harbor, or private Docker registry: +```bash +# Step 1: Create the Kubernetes secret +kubectl create secret docker-registry registry-credentials \ + --docker-server=artifactory.company.com \ + --docker-username=YOUR_USERNAME \ + --docker-password=YOUR_TOKEN \ + --namespace=permit-platform + +# Step 2: Verify secret was created +kubectl get secret registry-credentials -n permit-platform + +# Step 3: Update values.yaml +vi charts/permit-platform/values.yaml + +# Add this to global section: +# global: +# imageRegistry: "artifactory.company.com/permit-platform" +# imagePullSecrets: +# - registry-credentials + +# Step 4: Upgrade the Helm release +helm upgrade permit-platform charts/permit-platform -n permit-platform +``` + +**2. Forgot to Use --skip-images Flag** + +If you pushed images to a private registry but ran the installer WITHOUT `--skip-images`: +```bash +# Problem: Installer loaded wrong images from local tar files! +# Solution: Re-run installer with --skip-images flag + +# For GKE: +./scripts/install-permit-platform.sh --gke --skip-images + +# For other Kubernetes with private registry: +./scripts/install-permit-platform.sh --skip-images + +# For OpenShift with private registry: +./scripts/install-permit-platform.sh --openshift --skip-images +``` + +**3. Wrong imageRegistry Configuration** + +Check your `values.yaml` has the correct registry URL: +```bash +# View current configuration +kubectl get cm -n permit-platform + +# Verify imageRegistry matches where you pushed images +cat charts/permit-platform/values.yaml | grep imageRegistry + +# Should match your push command: +# If you ran: ./scripts/push-images-to-registry.sh us-central1-docker.pkg.dev/project/repo +# Then values.yaml must have: imageRegistry: "us-central1-docker.pkg.dev/project/repo" +``` + +**4. Images Not Pushed to Registry** + +Verify images actually exist in your registry: +```bash +# For GKE/Google Artifact Registry: +gcloud artifacts docker images list us-central1-docker.pkg.dev/PROJECT/REPO + +# For Artifactory: +curl -u username:password https://artifactory.company.com/v2/_catalog + +# For Harbor: +curl -u username:password https://harbor.company.com/v2/_catalog + +# For AWS ECR: +aws ecr describe-repositories --region us-east-1 +aws ecr list-images --repository-name permit-platform --region us-east-1 +``` + +**If images are missing, push them:** +```bash +cd permit-platform-installer +./scripts/push-images-to-registry.sh YOUR_REGISTRY_URL +``` + +**5. GKE Workload Identity / IAM Permissions** + +For GKE with Google Artifact Registry, ensure nodes have pull permissions: +```bash +# Grant Artifact Registry Reader role to GKE service account +gcloud projects add-iam-policy-binding PROJECT_ID \ + --member="serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com" \ + --role="roles/artifactregistry.reader" + +# Or for specific node pool service account: +gcloud projects add-iam-policy-binding PROJECT_ID \ + --member="serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \ + --role="roles/artifactregistry.reader" + +# Verify permissions +gcloud projects get-iam-policy PROJECT_ID \ + --flatten="bindings[].members" \ + --filter="bindings.role:roles/artifactregistry.reader" +``` + +**6. EKS with ECR - Missing IAM Role** + +For EKS with AWS ECR: +```bash +# Verify node IAM role has ECR pull permissions +aws iam get-role --role-name YOUR_NODE_ROLE_NAME + +# Add ECR read policy if missing +aws iam attach-role-policy \ + --role-name YOUR_NODE_ROLE_NAME \ + --policy-arn arn:aws:iam::aws:policy/AmazonEC2ContainerRegistryReadOnly +``` + +**7. AKS with ACR - Missing Role Assignment** + +For AKS with Azure Container Registry: +```bash +# Get AKS cluster identity +az aks show -g RESOURCE_GROUP -n CLUSTER_NAME --query identityProfile + +# Grant AcrPull role to AKS +az aks update -g RESOURCE_GROUP -n CLUSTER_NAME --attach-acr ACR_NAME + +# Verify access +az acr check-access --name ACR_NAME +``` + +**Quick Verification Commands:** + +```bash +# Check which images are failing +kubectl get pods -n permit-platform -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.status.containerStatuses[*].image}{"\t"}{.status.containerStatuses[*].state.waiting.reason}{"\n"}{end}' | grep ImagePull + +# Check all imagePullSecrets are configured +kubectl get deployment -n permit-platform -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.template.spec.imagePullSecrets[*].name}{"\n"}{end}' + +# Test pulling an image manually (on a cluster node) +kubectl run test-pull --image=YOUR_REGISTRY/permit-backend-v2:TAG --namespace=permit-platform --dry-run=client +``` + +
+
+
+

+ 💡 Prevention Tip: When using private registries, always follow this order: +

    +
  1. 1. Push images to registry (push-images-to-registry.sh)
    2. +
  2. 2. Create imagePullSecrets if needed (Artifactory/Harbor only)
    3. +
  3. 3. Configure values.yaml with imageRegistry and imagePullSecrets
    4. +
  4. 4. Run installer with --skip-images flag
    5. +
+ See Installation Guide Step 3.5 for complete workflow. +

+
+
+
+ ### Authentication and Login Issues