GCP Artifact Registry

--- name: "GCP Artifact Registry" description: "Use when you need to store, manage, and secure container images and language packages in Google Cloud. Essential for CI/CD pipelines, multi-region deployments, and artifact lifecycle management." metadata: author: "skynet" version: "1.0.0" category: "infrastructure" --- # GCP Artifact Registry ## Overview Google Cloud Artifact Registry is a fully managed service for storing and managing build artifacts including Docker container images, Maven and npm packages, and other dependencies. ## Prerequisites - Google Cloud CLI installed and authenticated - Project with Artifact Registry API enabled - Appropriate IAM permissions (roles/artifactregistry.admin or roles/artifactregistry.writer) ## Core Concepts - **Repository**: Container for artifacts of a specific format - **Format**: Type of artifacts (Docker, Maven, npm, Python, etc.) - **Location**: Regional or multi-regional storage - **Artifact**: Individual package or image stored in repository ## Essential Commands ### Repository Management #### Create Repository ```bash # Docker repository gcloud artifacts repositories create REPO_NAME \ --repository-format=docker \ --location=LOCATION \ --description="Description" # Maven repository gcloud artifacts repositories create maven-repo \ --repository-format=maven \ --location=us-central1 ``` #### List Repositories ```bash gcloud artifacts repositories list gcloud artifacts repositories list --location=us-central1 ``` #### Delete Repository ```bash gcloud artifacts repositories delete REPO_NAME --location=LOCATION ``` ### Docker Image Operations #### Configure Docker Authentication ```bash gcloud auth configure-docker LOCATION-docker.pkg.dev ``` #### Tag and Push Images ```bash # Tag image docker tag SOURCE_IMAGE LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG # Push image docker push LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG ``` #### Pull Images ```bash docker pull LOCATION-docker.pkg.dev/PROJECT_ID/REPO_NAME/IMAGE_NAME:TAG ``` ### Package Management #### Maven Configuration Add to `pom.xml`: ```xml <distributionManagement> <repository> <id>artifact-registry</id> <url>artifactregistry://LOCATION-maven.pkg.dev/PROJECT_ID/REPO_NAME</url> </repository> </distributionManagement> ``` #### npm Configuration ```bash # Set registry npm config set registry https://LOCATION-npm.pkg.dev/PROJECT_ID/REPO_NAME/ # Authenticate npx google-artifactregistry-auth ``` #### Python Package Setup ```bash # Configure pip pip config set global.index-url https://LOCATION-python.pkg.dev/PROJECT_ID/REPO_NAME/simple/ # Install package pip install PACKAGE_NAME ``` ## Decision Trees ### Choosing Repository Location ``` Multi-region needed? ├─ YES: Use multi-region (us, eu, asia) └─ NO: Single region needed? ├─ Low latency required: Choose closest region └─ Cost optimization: Choose cheapest region ``` ### Repository Format Selection ``` What artifact type? ├─ Container images → docker ├─ Java packages → maven ├─ JavaScript packages → npm ├─ Python packages → python └─ Generic files → generic ``` ## Common Workflows ### CI/CD Pipeline Integration ```bash #!/bin/bash # Build and push in CI/CD PROJECT_ID="your-project" REPO_NAME="app-repo" LOCATION="us-central1" IMAGE_NAME="myapp" TAG="${GITHUB_SHA:0:7}" # Build image docker build -t $IMAGE_NAME:$TAG . # Tag for registry docker tag $IMAGE_NAME:$TAG \ $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPO_NAME/$IMAGE_NAME:$TAG # Push image docker push $LOCATION-docker.pkg.dev/$PROJECT_ID/$REPO_NAME/$IMAGE_NAME:$TAG ``` ### Cleanup Old Artifacts ```bash # Delete images older than 30 days gcloud artifacts docker images list \ --repository=REPO_NAME \ --location=LOCATION \ --filter="createTime<'-P30D'" \ --format="value(package)" | \ xargs -I {} gcloud artifacts docker images delete {} --quiet ``` ### Cross-Project Access ```bash # Grant access to service account from another project gcloud artifacts repositories add-iam-policy-binding REPO_NAME \ --location=LOCATION \ --member="serviceAccount:SA_EMAIL" \ --role="roles/artifactregistry.reader" ``` ## Security and Access Control ### IAM Roles ```bash # Grant reader access gcloud artifacts repositories add-iam-policy-binding REPO_NAME \ --location=LOCATION \ --member="user:email@domain.com" \ --role="roles/artifactregistry.reader" # Grant writer access gcloud artifacts repositories add-iam-policy-binding REPO_NAME \ --location=LOCATION \ --member="group:developers@company.com" \ --role="roles/artifactregistry.writer" ``` ### Service Account Key Setup ```bash # Create service account gcloud iam service-accounts create artifact-registry-sa # Grant permissions gcloud projects add-iam-policy-binding PROJECT_ID \ --member="serviceAccount:artifact-registry-sa@PROJECT_ID.iam.gserviceaccount.com" \ --role="roles/artifactregistry.writer" # Create and download key gcloud iam service-accounts keys create key.json \ --iam-account=artifact-registry-sa@PROJECT_ID.iam.gserviceaccount.com ``` ## Monitoring and Management ### View Repository Details ```bash gcloud artifacts repositories describe REPO_NAME --location=LOCATION ``` ### List Artifacts ```bash # List Docker images gcloud artifacts docker images list --repository=REPO_NAME --location=LOCATION # List packages gcloud artifacts packages list --repository=REPO_NAME --location=LOCATION ``` ### Vulnerability Scanning ```bash # Enable scanning gcloud container images scan IMAGE_URL # View scan results gcloud container images describe IMAGE_URL --show-package-vulnerability ``` ## Troubleshooting ### Authentication Issues **Error**: `unauthorized: You don't have the needed permissions` ```bash # Check authentication gcloud auth list gcloud auth application-default login # Configure Docker gcloud auth configure-docker LOCATION-docker.pkg.dev ``` ### Permission Denied **Error**: `Permission "artifactregistry.repositories.uploadArtifacts" denied` ```bash # Check IAM bindings gcloud artifacts repositories get-iam-policy REPO_NAME --location=LOCATION # Add required role gcloud artifacts repositories add-iam-policy-binding REPO_NAME \ --location=LOCATION \ --member="user:$(gcloud config get-value account)" \ --role="roles/artifactregistry.writer" ``` ### Repository Not Found **Error**: `Repository not found` ```bash # Verify repository exists gcloud artifacts repositories list --location=LOCATION # Check location spelling gcloud artifacts locations list ``` ### Docker Push Fails **Error**: `denied: Token exchange failed for project` ```bash # Re-authenticate gcloud auth login gcloud auth configure-docker LOCATION-docker.pkg.dev # Check project ID gcloud config get-value project ``` ### Network Connectivity Issues ```bash # Test connectivity curl -I https://LOCATION-docker.pkg.dev # Check firewall rules gcloud compute firewall-rules list --filter="direction:EGRESS" ``` ## Best Practices - Use regional repositories for better performance - Implement artifact retention policies - Enable vulnerability scanning for container images - Use least privilege IAM roles - Tag images with semantic versioning - Automate cleanup of old artifacts - Monitor storage costs and usage