Troubleshoot Google Authentication

When using Cluster Shield for Container Vulnerability Management, you might need to authenticate to registries such as Google Container Registry (GCR) or Google Artifact Registry (GAR). This topic provides detailed instructions to troubleshoot authentication issues and correctly configure Cluster Shield with GCR and GAR.

Cluster Shield supports two primary authentication methods:

  • Service Account Key: User-managed and least secure
  • Docker Credential Helper: Recommended authentication method by GCP. It uses Google Application Default Credentials.

Authentication Using Service Account Key

  1. Create a Service Account:

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
--description="DESCRIPTION" \
--display-name="DISPLAY_NAME"

  2. Grant Artifact Registry Reader Role to the Service Account:

    gcloud artifacts repositories add-iam-policy-binding REPOSITORY \
  --location=LOCATION \
  --member=serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role=roles/artifactregistry.reader

  3. Create a Service Account Key:

    gcloud iam service-accounts keys create KEY_FILE \
--iam-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com

  4. Create the Kubernetes Secret:

    kubectl create secret docker-registry SECRET_NAME \
  --namespace=NAMESPACE \
  --docker-server=https://LOCATION-docker.pkg.dev \
  --docker-email=SERVICE-ACCOUNT-EMAIL \
  --docker-username=_json_key \
  --docker-password="$(cat KEY_FILE)"

​ Cluster Shield automatically uses this secret.

Authentication Using Docker Credential Helper

Docker Credential Helper utilizes Google Application Default Credentials (ADC).

Google Cloud Attached Service Account

GKE Autopilot clusters automatically attach service accounts; no manual configuration is required.

  1. Create Minimally Privileged Service Account:

    gcloud iam service-accounts create SA_NAME \
--display-name="DISPLAY_NAME" \
--project=PROJECT_ID

# Grant permissions
gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
  --role roles/container.defaultNodeServiceAccount

  2. Grant Artifact Registry Reader role to the Service Account:

    gcloud artifacts repositories add-iam-policy-binding REPOSITORY_NAME \
--project="REGISTRY_PROJECT_ID" \
--member=serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--role=roles/artifactregistry.reader

  3. Create the Node Pool:

    gcloud container node-pools create NODE_POOL_NAME \
--service-account=SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--cluster=CLUSTER_NAME

​ Cluster Shield automatically uses the attached service account.

Workload Identity Federation

Workload Identity Federation (WIF) provides secure, fine-grained authentication without direct service account keys.

Workload Identity Federation is enabled by default in GKE Autopilot clusters; no configuration required.

  1. Enable WIF:

    Applicable to standard clusters only.

    gcloud container clusters update CLUSTER_NAME \
--location=LOCATION \
--workload-pool=PROJECT_ID.svc.id.goog

  2. Configure the Node Pool:

    gcloud container node-pools create NODEPOOL_NAME \
--cluster=CLUSTER_NAME \
--region=COMPUTE_REGION \
--workload-metadata=GKE_METADATA

Impersonate an IAM Service Account Using a Kubernetes Service Account

  1. Create Kubernetes namespace:

    kubectl create namespace NAMESPACE

  2. Deploy Cluster Shield with Helm.

  3. Identify Kubernetes Service Account:

    kubectl get deployment -n NAMESPACE CLUSTER-SHIELD-DEPLOYMENT \
-o=jsonpath="{.spec.template.spec.serviceAccountName}"

  4. Bind Kubernetes Service Account to IAM Service Account:

    gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
--member="serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]" \
--role="roles/artifactregistry.reader"

  5. Annotate Kubernetes Service Account.

    kubectl annotate serviceaccount KSA_NAME -n NAMESPACE \
iam.gke.io/gcp-service-account=IAM_SA_NAME@PROJECT_ID.iam.gserviceaccount.com

​ Cluster Shield automatically starts using these credentials.

Advanced Troubleshooting

  • Check ADC Token:

    gcloud auth application-default print-access-token

  • Check Node Pool Configuration:

    gcloud container node-pools describe NODE_POOL_NAME --cluster=CLUSTER_NAME

  • Validate Kubernetes Service Account Annotations:

    kubectl get serviceaccount KSA_NAME -n NAMESPACE -o yaml

  • Verify IAM Permissions:

    gcloud projects get-iam-policy PROJECT_ID \
--flatten="bindings[].members" \
--format='table(bindings.role)' \
--filter="bindings.members:serviceAccount:SA_NAME@PROJECT_ID.iam.gserviceaccount.com"

Learn More