Before applying your configuration and installing the hybrid runtime, you should check
that your Kubernetes cluster is ready for Apigee hybrid installation.
To check the readiness of your cluster, you will create a YAML file with a Kubernetes Job definition and apply that file with kubectl commands to check the cluster.
You then check the status of the
Kubernetes test job with a kubectl get jobs command.
Verify that kubectl is set to the correct context using the following command.
The current context should be set to the cluster to which you are deploying Apigee hybrid.
kubectl config current-context
The result should include the name of the cluster you are deploying Apigee hybrid in. For
example, on GKE, the context name is usually in the form
gke_project-id_cluster-location_cluster-name, as
in:
gke_my-project_us-central1_my-cluster
If the name cluster name in the context does not match, the following command will get the
gcloud credentials of the cluster and set the kubectl context:
You have now made sure your Apigee hybrid cluster is ready. Next, let's apply your
configuration to the hybrid runtime and complete your installation of Apigee hybrid.
Troubleshooting
Cassandra DNS check: If you find error logs smiliar to
DNS resolution was successful but IP doesn't match POD IP,
could not resolve hostname or error determining hostname it means your
cluster DNS is not configured correctly for a multi-region setup. You can ignore this error if
you do not intend to setup multi-region.
Control Plane connectivity check: If you find error logs similar to
error creating TCP connection with host then you need to resolve the connectivity
from cluster to apigee.googleapis.com and re-run the job.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-26 UTC."],[[["\u003cp\u003eThis documentation provides instructions on how to check if a Kubernetes cluster is ready for Apigee hybrid installation using a pre-install cluster check feature.\u003c/p\u003e\n"],["\u003cp\u003eTo perform the cluster readiness check, you will need to verify \u003ccode\u003ekubectl\u003c/code\u003e context, create a YAML file with a Kubernetes Job definition, apply the file using \u003ccode\u003ekubectl\u003c/code\u003e, and check the job status.\u003c/p\u003e\n"],["\u003cp\u003eA successful cluster check will display a \u003ccode\u003e1/1\u003c/code\u003e completion status, whereas a failed check will display a \u003ccode\u003e0/1\u003c/code\u003e status, and troubleshooting steps are provided if the test fails.\u003c/p\u003e\n"],["\u003cp\u003eIf DNS resolution errors occur, a workaround is provided which suggests adding a static host entry in the \u003ccode\u003e/etc/hosts\u003c/code\u003e file of each Cassandra worker node, or that this error can be ignored if a multi-region setup is not needed.\u003c/p\u003e\n"],["\u003cp\u003eAfter the cluster readiness check, the next steps to be carried out are applying the configuration to the hybrid runtime and finishing the Apigee hybrid installation.\u003c/p\u003e\n"]]],[],null,["# Step 8: Check cluster readiness\n\n| You are currently viewing version 1.10 of the Apigee hybrid documentation. **This version is end of life.** You should upgrade to a newer version. For more information, see [Supported versions](/apigee/docs/hybrid/supported-platforms#supported-versions).\n|\n| **Preview\n| --- Pre-install cluster check**\n|\n|\n| This feature is subject to the \"Pre-GA Offerings Terms\" in the General Service Terms section\n| of the [Service Specific Terms](/terms/service-terms#1).\n|\n| Pre-GA features are available \"as is\" and might have limited support.\n|\n| For more information, see the\n| [launch stage descriptions](/products#product-launch-stages).\n\nCheck hybrid cluster readiness\n------------------------------\n\nBefore applying your configuration and installing the hybrid runtime, you should check\nthat your Kubernetes cluster is ready for Apigee hybrid installation.\n| Note. This feature is in public preview. The scope of the checks is limited.\n\n\nTo check the readiness of your cluster, you will create a YAML file with a Kubernetes Job definition and apply that file with `kubectl` commands to check the cluster.\nYou then check the status of the\nKubernetes test job with a `kubectl get jobs` command.\n\n1. Verify that `kubectl` is set to the correct context using the following command. The current context should be set to the cluster to which you are deploying Apigee hybrid. \n\n ```\n kubectl config current-context\n ```\n\n The result should include the name of the cluster you are deploying Apigee hybrid in. For\n example, on GKE, the context name is usually in the form\n `gke_`\u003cvar translate=\"no\"\u003eproject-id\u003c/var\u003e`_`\u003cvar translate=\"no\"\u003ecluster-location\u003c/var\u003e`_`\u003cvar translate=\"no\"\u003ecluster-name\u003c/var\u003e, as\n in: \n\n ```\n gke_my-project_us-central1_my-cluster\n ```\n\n If the name cluster name in the context does not match, the following command will get the\n `gcloud` credentials of the cluster and set the `kubectl` context:\n\n ### Regional clusters\n\n ```\n gcloud container clusters get-credentials $CLUSTER_NAME \\\n --region $CLUSTER_LOCATION \\\n --project $PROJECT_ID\n ```\n\n ### Zonal clusters\n\n ```\n gcloud container clusters get-credentials $CLUSTER_NAME \\\n --zone $CLUSTER_LOCATION \\\n --project $PROJECT_ID\n ```\n2. In your hybrid files directory, create a `cluster-check` directory: \n\n ```\n mkdir $HYBRID_FILES/cluster-check\n ```\n3. In the `$HYBRID_FILES/cluster-check` directory, create a file named `apigee-k8s-cluster-ready-check.yaml` with the following contents: \n\n ```\n apiVersion: v1\n kind: ServiceAccount\n metadata:\n name: apigee-k8s-cluster-ready-check\n ---\n apiVersion: batch/v1\n kind: Job\n metadata:\n name: apigee-k8s-cluster-ready-check\n spec:\n template:\n spec:\n hostNetwork: true\n serviceAccountName: apigee-k8s-cluster-ready-check\n containers:\n - name: manager\n image: gcr.io/apigee-release/hybrid/apigee-operators:1.10.0\n command:\n - /manager\n args:\n - --k8s-cluster-ready-check\n env:\n - name: POD_IP\n valueFrom:\n fieldRef:\n fieldPath: status.podIP\n securityContext:\n runAsGroup: 998\n runAsNonRoot: true\n runAsUser: 999\n restartPolicy: Never\n backoffLimit: 1\n ```\n4. Apply the `apigee-k8s-cluster-ready-check.yaml` with the following `kubectl` command. This will run the test: \n\n ```\n kubectl apply -f $HYBRID_FILES/cluster-check/apigee-k8s-cluster-ready-check.yaml\n ```\n5. Check the status of the Kubernetes job with the following command: \n\n ```\n kubectl get jobs apigee-k8s-cluster-ready-check\n ```\n\n\n If your cluster is ready, the output should look something like: \n\n ```\n NAME COMPLETIONS DURATION AGE\n apigee-k8s-cluster-ready-check 1/1 8s 1h23m\n ```\n\n\n If the test failed and your cluster is not ready, the output should look something like: \n\n ```\n NAME COMPLETIONS DURATION AGE\n apigee-k8s-cluster-ready-check 0/1 44s 44s\n ```\n\n Look for the number of completions:\n - **1/1** Success, your cluster is ready for Apigee hybrid installation.\n - **0/1** The test failed. The cluster is not ready. Proceed to the following steps to troubleshoot the cluster.\n\n \u003cbr /\u003e\n\n6. If the test did not succeed, check the logs with the following commands.\n 1. Get the name of the pod for the cluster pre-check job: \n\n ```\n kubectl get pods | grep apigee-k8s-cluster-ready-check\n ```\n 2. Get the Kubernetes logs for the pod: \n\n ```\n kubectl logs pod_name\n ```\n\n\n Where \u003cvar translate=\"no\"\u003epod_name\u003c/var\u003e is the name of the apigee-k8s-cluster-ready-check pod.\n7. Clean up before proceeding to the next step. Delete the Kubernetes job with the following command: \n\n ```\n kubectl delete -f $HYBRID_FILES/cluster-check/apigee-k8s-cluster-ready-check.yaml\n ```\n\n| **Tip:** On some platforms, like Anthos on Bare Metal or GKE on-prem, you may see DNS resolution errors. If the DNS resolution is not working, try this workaround.\n|\n|\n| Add a static host entry in `/etc/hosts` file of each cassandra worker node\n| similar to the following: \n|\n| ```\n| echo -e \"\\\\n127.0.1.1 ${HOSTNAME}\" \u003e\u003e \"/etc/hosts\"\n| ```\n|\n|\n| or \n|\n| ```\n| \"\\\\nWORKER-NODE-IP ${HOSTNAME}\" \u003e\u003e \"/etc/hosts\"\n| ```\n\nYou have now made sure your Apigee hybrid cluster is ready. Next, let's apply your\nconfiguration to the hybrid runtime and complete your installation of Apigee hybrid.\n\nTroubleshooting\n---------------\n\n1. Cassandra DNS check: If you find error logs smiliar to `DNS resolution was successful but IP doesn't match POD IP`, `could not resolve hostname` or `error determining hostname` it means your cluster DNS is not configured correctly for a multi-region setup. You can ignore this error if you do not intend to setup multi-region.\n2. Control Plane connectivity check: If you find error logs similar to `error creating TCP connection with host` then you need to resolve the connectivity from cluster to apigee.googleapis.com and re-run the job.\n\n[1](/apigee/docs/hybrid/v1.10/install-create-cluster) [2](/apigee/docs/hybrid/v1.10/install-cert-manager) [3](/apigee/docs/hybrid/v1.10/install-apigeectl) [4](/apigee/docs/hybrid/v1.10/install-service-accounts) [5](/apigee/docs/hybrid/v1.10/install-create-tls-certificates) [6](/apigee/docs/hybrid/v1.10/install-configure-cluster) [7](/apigee/docs/hybrid/v1.10/install-enable-synchronizer-access) [8](/apigee/docs/hybrid/v1.10/install-check-cluster) [(NEXT) Step 9: Install the hybrid runtime](/apigee/docs/hybrid/v1.10/install-hybrid-runtime) [10](/apigee/docs/hybrid/v1.10/install-expose-apigee-ingress) [11](/apigee/docs/hybrid/v1.10/install-deploy-proxy)\n\n\u003cbr /\u003e"]]
