Add Kubernetes Cluster

First click Integrations from the left sidebar and select the integration tab. Then choose Kubernetes.

Codefresh integrations

In the Kubernetes integration window, you will be able to add a cluster from known providers such as GKE or by manually adding your cluster settings.

Adding GKE Cluster

Adding a cluster in GKE can be done by clicking the Add cluster button under Google Cloud Provider and selecting the desired project and cluster.

If this is your first time you’ll be prompted to authenticate using your google credentials, make sure you’re doing so with a user that have access to your GKE projects.

If you are a new customer of Google Cloud, you are also eligible to receive a Codefresh offer to get up to $500 in Google credits. As soon at the GKE integration is complete within Codefresh, you will get an email with extra details on how to claim your credits.

Follow the link in the email to fill in an application for the free credits. Once Google approves the application (usually within 1-2 days) your credits will be available to your account. Make sure to check your spam folder for that email.

Adding EKS Cluster

To add an Amazon EKS cluster, you must first create a service account and obtain a token used to manage the integration.

The official Amazon-provided guide on EKS can be found here.

In order to use your cluster locally with kubectl, you must first install the heptio-authenticator-aws binary. Your version of kubectl must also be 1.10+ for this to work.

Next, create a kubeconfig file, such as ~/.kube/eks, replacing <endpoint-url>, <base64-encoded-ca-cert>, and <cluster-name> with information on your EKS cluster obtained in the AWS console:

apiVersion: v1
- cluster:
    server: <endpoint-url>
    certificate-authority-data: <base64-encoded-ca-cert>
  name: kubernetes
- context:
    cluster: kubernetes
    user: aws
  name: aws
current-context: aws
kind: Config
preferences: {}
- name: aws
      command: heptio-authenticator-aws
        - "token"
        - "-i"
        - "<cluster-name>"

Then, in an environment that has access to your AWS account, run the following command to create an admin user service account and necessary role binding:

cat <<EOF | kubectl --kubeconfig="$HOME/.kube/eks" apply -f -
apiVersion: v1
kind: ServiceAccount
  name: admin-user
  namespace: kube-system
kind: ClusterRoleBinding
  name: admin-user
  kind: ClusterRole
  name: cluster-admin
- kind: ServiceAccount
  name: admin-user
  namespace: kube-system

Finally, use the following command to obtain the service account token:

kubectl --kubeconfig="$HOME/.kube/eks" -n="kube-system" get secret \
  $(kubectl --kubeconfig="$HOME/.kube/eks" -n="kube-system" get secret | \
    grep admin-user | awk '{print $1}') -o jsonpath="{.data.token}"

Once you have this token, follow the steps in the section below, using this token for item #4.

Adding any other cluster type (not dependent on any provider)

On your Configuration settings (left-menu), go to the Integration tab and choose Kubernetes
In order to add any other type of cluster, outside of GKE, use Custom Providers

Adding a custom cluster in Codefresh

Adding a custom K8s cluster in Codefresh

The integration between Codefresh and your Kubernetes cluster is API based and relies on a Kubernetes service account of your choosing that will be used to manage the integration.

The configurations you’ll be required to add are:

  1. Name - Any name of your choosing, that will represent your cluster context in Codefresh.
  1. Host - The endpoint for your Kubernetes API
  1. Certificate - The Kubernetes service account certificate used for the integration with Codefresh
  1. Token - The Kubernetes service account token used for the integration with Codefresh

Adding a custom cluster in Codefresh - details

In the section below we’ll provide you with easy instructions how to get all your cluster configurations in order to add it to Codefresh.

Get cluster configurations

Copy and paste the below commands into your local shell, then save the outputs and paste them into Codefresh. The commands rely on kubectl so make sure it is configured against your cluster.

More than one cluster in kubeconfig?

Before starting, make sure that you local context is the one you’de like to add to Codefresh.
Switch to the desired context before continue

Host IP

export CURRENT_CONTEXT=$(kubectl config current-context) && export CURRENT_CLUSTER=$(kubectl config view -o go-template="{{\$curr_context := \"$CURRENT_CONTEXT\" }}{{range .contexts}}{{if eq .name \$curr_context}}{{.context.cluster}}{{end}}{{end}}") && echo $(kubectl config view -o go-template="{{\$cluster_context := \"$CURRENT_CLUSTER\"}}{{range .clusters}}{{if eq .name \$cluster_context}}{{.cluster.server}}{{end}}{{end}}")


echo $(kubectl get secret -o go-template='{{index .data "ca.crt" }}' $(kubectl get sa default -o go-template="{{range .secrets}}{{.name}}{{end}}"))


echo $(kubectl get secret -o go-template='{{index .data "token" }}' $(kubectl get sa default -o go-template="{{range .secrets}}{{.name}}{{end}}"))

In the instructions above, we’re reffering for a service account named ‘default’ in regards to the certificate and token. You can provide any service account configurations you may have on any namespace, as long as it has the correct permissions. The cluster actions you’ll be limited to in Codefresh are based on the Kubernetes service account permissions you set in Kubernetes RBAC.

The minimum permissions Codefresh needs to work with the cluster are the following:


kind: ClusterRole
  name: codefresh-role
  - apiGroups: [""]
    resources: ["*"]
    verbs: ["list", "watch", "get"] 

Once the cluster been added successfully you can go to the Kubernetes tab to start working with the services of your cluster.

So, what’s next?

Troubleshooting cluster addition

After adding your cluster configurations and in case the test fails, click “Save” to get the error message back.


Error: Cannot list namespaces

Add Cluster Error

Failed to add cluster: namespaces is forbidden: User "system:serviceaccount:default:default" cannot list namespaces at the cluster scope

The service account used for the integration doesn’t have the minimal permissions required. To fix this add a service account that have the required permissions.

The easiest way to do this is to create a cluster binding role between the default service account and cluster-admin role:

Create cluster binding with admin permissions

kubectl create clusterrolebinding default-admin --clusterrole cluster-admin --serviceaccount=default:default

Kubernetes cluster - using an external reverse proxy (edge case)

In case you’re using an external reverse proxy to manage inbound traffic to your Kubernetes API, please read this article to make sure your certificate setup are managed correctly in order to add your cluster successfully to Codefresh.