Skip to content

Commit 1a8e59e

Browse files
EliMoshkovichEliMoshkovich
authored
gke update and imagePullSecrets (#607)
* gke update and imagePullSecrets * private registry section have been added
1 parent 3bf031a commit 1a8e59e

5 files changed

Lines changed: 704 additions & 10 deletions

File tree

‎docs/how-to/deploy/on-prem/installation.mdx‎

Lines changed: 263 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -550,6 +550,246 @@ cat ~/.ssh/id_rsa # or your specific key file
550550
</div>
551551
</div>
552552

553+
## Step 3.5: Push Images to Private Registry (GKE Example)
554+
555+
<div className="bg-blue-50 border-l-4 border-blue-400 p-4 my-4">
556+
<div className="flex">
557+
<div className="ml-3">
558+
<p className="text-sm text-blue-700">
559+
<strong>Optional:</strong> 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.
560+
</p>
561+
</div>
562+
</div>
563+
</div>
564+
565+
### Prerequisites for GKE Registry
566+
567+
Before pushing images, you need to:
568+
569+
1. **Create a Google Artifact Registry repository** (this is NOT done by the script):
570+
571+
```bash
572+
# Authenticate with Google Cloud
573+
gcloud auth login
574+
575+
# Set your project
576+
gcloud config set project YOUR_PROJECT_ID
577+
578+
# Create Artifact Registry repository
579+
gcloud artifacts repositories create permit-platform \
580+
--repository-format=docker \
581+
--location=us-central1 \
582+
--project=YOUR_PROJECT_ID
583+
584+
# Configure Docker authentication
585+
gcloud auth configure-docker us-central1-docker.pkg.dev
586+
```
587+
588+
2. **Verify authentication**:
589+
590+
```bash
591+
# Test that Docker can authenticate to GAR
592+
docker pull us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform/hello-world || echo "Authentication configured"
593+
```
594+
595+
### Push Images to Google Artifact Registry
596+
597+
The installer package includes a convenience script to push all images to your GKE registry:
598+
599+
```bash
600+
# Navigate to scripts directory
601+
cd scripts
602+
603+
# Push to Google Artifact Registry (example for us-central1)
604+
./push-images-to-registry.sh us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform
605+
```
606+
607+
**What this script does:**
608+
609+
1. Loads all ~35 images from the tar files in the `images/` directory
610+
2. Tags each image for your target registry (preserving original version tags)
611+
3. Pushes both the original tag and `:latest` tag to your registry
612+
4. **Automatically updates** `charts/permit-platform/values.yaml` with your registry URL
613+
5. Creates a timestamped backup of your original values.yaml
614+
615+
**Expected output:**
616+
617+
```bash
618+
╔══════════════════════════════════════════════════════════════╗
619+
║ Permit Platform Image Push Script ║
620+
╚══════════════════════════════════════════════════════════════╝
621+
622+
Target Registry: us-central1-docker.pkg.dev/my-project/permit-platform
623+
Images Directory: ../images
624+
625+
Found 35 images to push
626+
627+
[1/35] Processing permit-backend-v2.tar
628+
Loading image from tar...
629+
Loaded: permitio/permit-backend-v2:latest
630+
Tagging as us-central1-docker.pkg.dev/my-project/permit-platform/permit-backend-v2:latest
631+
Pushing...
632+
✓ Done
633+
634+
[2/35] Processing permit-frontend.tar
635+
...
636+
637+
╔══════════════════════════════════════════════════════════════╗
638+
║ All images pushed successfully! ║
639+
╚══════════════════════════════════════════════════════════════╝
640+
641+
Updating values.yaml with registry: us-central1-docker.pkg.dev/my-project/permit-platform
642+
✅ Updated values.yaml with imageRegistry: "us-central1-docker.pkg.dev/my-project/permit-platform"
643+
644+
Next steps:
645+
1. Update charts/permit-platform/values.yaml with your frontend domain:
646+
frontendDomain: "your-domain.company.com"
647+
648+
2. Run the installer with --skip-images flag:
649+
cd scripts
650+
./install-permit-platform.sh --gke --skip-images
651+
```
652+
653+
**Time and storage requirements:**
654+
- **Time**: 10-20 minutes depending on network speed
655+
- **Bandwidth**: ~12GB upload
656+
- **Registry storage**: ~12GB required in GAR
657+
658+
### Verify Images in Registry
659+
660+
After pushing, verify images are accessible:
661+
662+
```bash
663+
# List all images in your GAR repository
664+
gcloud artifacts docker images list us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform
665+
666+
# Check a specific image
667+
gcloud artifacts docker images describe \
668+
us-central1-docker.pkg.dev/YOUR_PROJECT_ID/permit-platform/permit-backend-v2:latest
669+
```
670+
671+
### Using Other Private Registries
672+
673+
While this guide focuses on GKE with Google Artifact Registry, the `push-images-to-registry.sh` script works with any Docker-compatible registry:
674+
675+
- **AWS ECR**: `123456789012.dkr.ecr.us-east-1.amazonaws.com/permit-platform`
676+
- **Azure ACR**: `myregistry.azurecr.io/permit-platform`
677+
- **JFrog Artifactory**: `artifactory.company.com/permit-platform`
678+
- **Harbor**: `harbor.company.com/permit-platform`
679+
680+
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`.
681+
682+
#### Important: Registry Authentication for Kubernetes
683+
684+
<div className="bg-red-50 border-l-4 border-red-400 p-4 my-4">
685+
<div className="flex">
686+
<div className="ml-3">
687+
<p className="text-sm text-red-700">
688+
<strong>⚠️ Critical:</strong> 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.
689+
</p>
690+
</div>
691+
</div>
692+
</div>
693+
694+
**When you need imagePullSecrets:**
695+
- ✅ **GKE with GAR/GCR**: Not needed (GKE nodes authenticate automatically via Workload Identity)
696+
- ✅ **EKS with ECR**: Not needed (EKS nodes authenticate automatically via IAM roles)
697+
- ✅ **AKS with ACR**: Not needed (AKS nodes authenticate automatically via managed identity)
698+
- ❌ **JFrog Artifactory**: Required (needs username/password or token)
699+
- ❌ **Harbor**: Required (needs username/password)
700+
- ❌ **Private Docker registries**: Required (needs authentication)
701+
702+
**How to configure imagePullSecrets:**
703+
704+
1. **Create the Kubernetes secret** before installation:
705+
706+
```bash
707+
# For registries requiring username/password (Artifactory, Harbor, etc.)
708+
kubectl create secret docker-registry registry-credentials \
709+
--docker-server=artifactory.company.com \
710+
--docker-username=YOUR_USERNAME \
711+
--docker-password=YOUR_PASSWORD_OR_TOKEN \
712+
--docker-email=your-email@company.com \
713+
--namespace permit-platform
714+
715+
# Verify secret was created
716+
kubectl get secret registry-credentials -n permit-platform
717+
```
718+
719+
2. **Configure imagePullSecrets in your values.yaml** file:
720+
721+
The Helm chart now supports `global.imagePullSecrets`. Add this to your `charts/permit-platform/values.yaml`:
722+
723+
```yaml
724+
global:
725+
imageRegistry: "artifactory.company.com/permit-platform"
726+
imagePullPolicy: "IfNotPresent"
727+
728+
# Add your image pull secrets here
729+
imagePullSecrets:
730+
- registry-credentials
731+
```
732+
733+
**That's it!** The Helm chart will automatically apply the imagePullSecrets to all deployments and jobs.
734+
735+
**Multiple secrets example:**
736+
737+
```yaml
738+
global:
739+
imagePullSecrets:
740+
- registry-credentials
741+
- backup-registry-credentials
742+
```
743+
744+
<div className="bg-green-50 border-l-4 border-green-400 p-4 my-4">
745+
<div className="flex">
746+
<div className="ml-3">
747+
<p className="text-sm text-green-700">
748+
<strong>✅ Simplified:</strong> As of January 2026, the Helm chart includes built-in support for <code>global.imagePullSecrets</code>. No manual template editing required!
749+
</p>
750+
</div>
751+
</div>
752+
</div>
753+
754+
**Alternative: Use node-level registry authentication** (if supported by your Kubernetes distribution)
755+
756+
### Important: Skip Image Loading When Using Private Registry
757+
758+
<div className="bg-blue-50 border-l-4 border-blue-400 p-4 my-4">
759+
<div className="flex">
760+
<div className="ml-3">
761+
<p className="text-sm text-blue-700">
762+
<strong>Note:</strong> If you pushed images to a private registry (GKE/GAR, Artifactory, Harbor, etc.) using the <code>push-images-to-registry.sh</code> script, you MUST use the <code>--skip-images</code> flag when running the installer. This prevents the installer from trying to load images from local tar files.
763+
</p>
764+
</div>
765+
</div>
766+
</div>
767+
768+
**Correct usage when images are in your registry:**
769+
770+
```bash
771+
# After pushing images to your private registry, run installer with --skip-images
772+
cd scripts
773+
./install-permit-platform.sh --gke --skip-images # For GKE
774+
./install-permit-platform.sh --skip-images # For EKS/AKS/on-prem
775+
./install-permit-platform.sh --openshift --skip-images # For OpenShift
776+
```
777+
778+
**When NOT to use --skip-images:**
779+
- Installing from the tar.gz package for the first time
780+
- Using Docker Hub public images
781+
- Images are loaded to local Docker daemon (Kind clusters)
782+
783+
<div className="bg-green-50 border-l-4 border-green-400 p-4 my-4">
784+
<div className="flex">
785+
<div className="ml-3">
786+
<p className="text-sm text-green-700">
787+
<strong>✅ Ready:</strong> After pushing images to your registry and configuring values.yaml with imagePullSecrets, proceed to Step 4 to run the installation with <code>--skip-images</code> flag.
788+
</p>
789+
</div>
790+
</div>
791+
</div>
792+
553793
## Step 4: Run Installation
554794

555795
### Complete Installation Options Reference
@@ -587,6 +827,29 @@ The installer script `./scripts/install-permit-platform.sh` provides comprehensi
587827
# - Handles OpenShift-specific networking
588828
```
589829

830+
#### Google GKE Deployment
831+
```bash
832+
# Deploy to Google Kubernetes Engine
833+
./scripts/install-permit-platform.sh --gke
834+
835+
# What it does:
836+
# - Configures for GKE-specific settings
837+
# - Handles GKE networking and storage
838+
# - Compatible with both GKE Standard and Autopilot
839+
# - Works with Google Artifact Registry (GAR) or GCR
840+
# - Installs nginx-ingress-controller (if not present)
841+
```
842+
843+
<div className="bg-blue-50 border-l-4 border-blue-400 p-4 my-4">
844+
<div className="flex">
845+
<div className="ml-3">
846+
<p className="text-sm text-blue-700">
847+
<strong>Note:</strong> GKE deployments require nginx-ingress-controller for ingress routing. The installer will set this up if not already installed in your cluster.
848+
</p>
849+
</div>
850+
</div>
851+
</div>
852+
590853
#### Local Development (Kind)
591854
```bash
592855
# Deploy to local Kind cluster for development

0 commit comments

Comments
 (0)