Prepare the target cluster¶

Follow this guide to create a service account and generate a kubeconfig file from a target cluster. These are the only steps required to be performed in the target cluster.

For manual configuration, go to Manual Configuration, otherwise proceed to Setup Script.

Note

If your target cluster is under a server proxy for external communication, like those present on platforms like Rancher, we recommend generating a kubeconfig file through your own platform.

Normally these platforms handle their own tokens instead of a service account token.

Zora requires read-only access, as described here.

Setup Script¶

A script is available to prepare a cluster, which can be executed by any POSIX compliant shell.

curl -q https://zora-docs.undistro.io/v0.5/targetcluster.sh | sh

By default, the script uses the current context. But it's possible to set the target cluster context by exporting the CONTEXT:

curl -q https://zora-docs.undistro.io/v0.5/targetcluster.sh | CONTEXT=<TARGET_CONTEXT> sh

Or switching the current context via kubectl before running the script:

kubectl config use-context <TARGET_CONTEXT>
curl -q https://zora-docs.undistro.io/v0.5/targetcluster.sh | sh

The generated kubeconfig will be named as your Kuberntes context suffixed with -kubeconfig.yaml, by default.

Before finishing, the script will show a command to connect the target cluster through the generated kubeconfig, and save a sample Cluster manifest.

A complete list of customizable environment variables can be seen on the table below.

Environment Variable	Description
`SVC_ACCOUNT_NS`	Service Account namespace, defaults to `zora-system`
`SVC_ACCOUNT_NAME`	Service Account name, defaults to `zora-view`
`CLUSTER_ROLE_NAME`	Cluster Role name, defaults to `zora-view`
`SVC_ACCOUNT_SECRET_NS`	Service Account Secret namespace, defaults to the value of `SVC_ACCOUNT_NS`
`SVC_ACCOUNT_SECRET_NAME`	Service Account Secret name, defaults to the of value of `SVC_ACCOUNT_NAME` with the "-token" suffix
`KCONFIG_SECRET_NAME`	Name of the displayed kubeconfig Secret, defaults to the value of `CLUSTER_NAME` with the "-kubeconfig" suffix
`TOKEN_NAME`	Uses the value of `SVC_ACCOUNT_SECRET_NAME` or the one generated by K8s, according to the cluster version
`CONTEXT`	K8s context, using the current one as default
`CLUSTER_NAME`	Cluster name from the `CONTEXT` variable
`CLUSTER_NS`	Cluster namespace used on the manifest sample, defaults to the value of `SVC_ACCOUNT_NS`
`CLUSTER_CA`	Cluster Certificate Authority, extracted according to `CONTEXT`
`CLUSTER_SERVER`	Cluster server address, extracted according to `CONTEXT`
`KCONFIG_NAME`	Name of the generated kubeconfig, defaulting to the value of `CONTEXT` plus the string "_kubeconfig.yaml"
`SAMPLE_MANIFEST_NAME`	Name of the `Cluster` manifest sample, defaults to `cluster_sample.yaml` plus the K8s context as prefix

The next instructions explain how to manually configure your target clusters.

Manual Configuration¶

The target cluster can be configured through the steps described in the next sections.

1. Access the target cluster ¶

First, make sure you are in the context of the target cluster. You can do this by the following commands:

Display list of contexts: kubectl config get-contexts
Display the current-context: kubectl config current-context
Set the default context to my-target-cluster: kubectl config use-context my-target-cluster

2. Create the RBAC resources¶

Create the service account in a separate namespace and configure view permissions. The token generated by this service account will be used in the kubeconfig file.

Important

You should create a separate service account in the target cluster to connect it to Zora. This is required because the kubeconfig files generated by most cloud providers, call CLI commands, such as aws or gcloud, those can’t be called by Zora.

kubectl create namespace zora-system
kubectl -n zora-system create serviceaccount zora-view
cat << EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: zora-view
rules:
  - apiGroups: [ "" ]
    resources:
      - configmaps
      - endpoints
      - limitranges
      - namespaces
      - nodes
      - persistentvolumes
      - persistentvolumeclaims
      - pods
      - replicationcontrollers
      - secrets
      - serviceaccounts
      - services
    verbs: [ "get", "list" ]
  - apiGroups: [ "apps" ]
    resources:
      - daemonsets
      - deployments
      - statefulsets
      - replicasets
    verbs: [ "get", "list" ]
  - apiGroups: [ "autoscaling" ]
    resources:
      - horizontalpodautoscalers
    verbs: [ "get", "list" ]
  - apiGroups: [ "networking.k8s.io" ]
    resources:
      - ingresses
      - networkpolicies
    verbs: [ "get", "list" ]
  - apiGroups: [ "policy" ]
    resources:
      - poddisruptionbudgets
      - podsecuritypolicies
    verbs: [ "get", "list" ]
  - apiGroups: [ "rbac.authorization.k8s.io" ]
    resources:
      - clusterroles
      - clusterrolebindings
      - roles
      - rolebindings
    verbs: [ "get", "list" ]
  - apiGroups: [ "metrics.k8s.io" ]
    resources:
      - pods
      - nodes
    verbs: [ "get", "list" ]
  - apiGroups: [ batch ]
    resources:
      - jobs
      - cronjobs
    verbs: [ "get", "list" ]
  - apiGroups: [ admissionregistration.k8s.io ]
    resources:
      - validatingwebhookconfigurations
      - mutatingwebhookconfigurations
    verbs: [ "get", "list" ]
EOF
kubectl create clusterrolebinding zora-view --clusterrole=zora-view --serviceaccount=zora-system:zora-view

Info

Zora requires just view permissions of your target clusters.

3. Set up the environment variables¶

Set up the following environment variables based on the Kubernetes version of the target cluster.

You can verify the version of your cluster by running:

kubectl version

The Server Version is the version of Kubernetes your target cluster is running.

Kubernetes prior to 1.24.0Kubernetes 1.24.0 or later

export TOKEN_NAME=$(kubectl -n zora-system get serviceaccount zora-view -o=jsonpath='{.secrets[0].name}')
export TOKEN_VALUE=$(kubectl -n zora-system get secret ${TOKEN_NAME} -o=jsonpath='{.data.token}' | base64 --decode)
export CURRENT_CONTEXT=$(kubectl config current-context)
export CURRENT_CLUSTER=$(kubectl config view --raw -o=go-template='{{range .contexts}}{{if eq .name "'''${CURRENT_CONTEXT}'''"}}{{ index .context "cluster" }}{{end}}{{end}}')
export CLUSTER_CA=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name "'''${CURRENT_CLUSTER}'''"}}"{{with index .cluster "certificate-authority-data" }}{{.}}{{end}}"{{ end }}{{ end }}')
export CLUSTER_SERVER=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name "'''${CURRENT_CLUSTER}'''"}}{{ .cluster.server }}{{end}}{{ end }}')

export TOKEN_NAME="zora-view-token"
cat << EOF | kubectl apply -f - 
apiVersion: v1
kind: Secret
metadata:
    name: "$TOKEN_NAME"
    namespace: "zora-system"
    annotations:
        kubernetes.io/service-account.name: "zora-view"
type: kubernetes.io/service-account-token
EOF
export TOKEN_VALUE=$(kubectl -n zora-system get secret ${TOKEN_NAME} -o=jsonpath='{.data.token}' | base64 --decode)
export CURRENT_CONTEXT=$(kubectl config current-context)
export CURRENT_CLUSTER=$(kubectl config view --raw -o=go-template='{{range .contexts}}{{if eq .name "'''${CURRENT_CONTEXT}'''"}}{{ index .context "cluster" }}{{end}}{{end}}')
export CLUSTER_CA=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name "'''${CURRENT_CLUSTER}'''"}}"{{with index .cluster "certificate-authority-data" }}{{.}}{{end}}"{{ end }}{{ end }}')
export CLUSTER_SERVER=$(kubectl config view --raw -o=go-template='{{range .clusters}}{{if eq .name "'''${CURRENT_CLUSTER}'''"}}{{ .cluster.server }}{{end}}{{ end }}')

4. Generate a kubeconfig file¶

Generate a file with kubeconfig data, based on the environment variables defined before:

cat << EOF > zora-view-kubeconfig.yml
apiVersion: v1
kind: Config
current-context: ${CURRENT_CONTEXT}
contexts:
- name: ${CURRENT_CONTEXT}
  context:
    cluster: ${CURRENT_CONTEXT}
    user: zora-view
clusters:
- name: ${CURRENT_CONTEXT}
  cluster:
    certificate-authority-data: ${CLUSTER_CA}
    server: ${CLUSTER_SERVER}
users:
- name: zora-view
  user:
    token: ${TOKEN_VALUE}
EOF

Example of a generated kubeconfig file

apiVersion: v1
kind: Config
current-context: mycluster-prod
contexts:
- name: mycluster-prod
  context:
    cluster: mycluster-prod
    user: zora-view
clusters:
- name: mycluster-prod
  cluster:
    certificate-authority-data: LS0tLS1CRUdJTiBDRVJU...OMITTED
    server: https://OMITTED.us-east-1.eks.amazonaws.com
users:
- name: zora-view
  user:
    token: eyJhbGciOiJSUzI1NiIs...OMITTED

Verify the generated kubeconfig¶

These steps create a file in your current working directory called zora-view-kubeconfig.yml. The contents of this file are used in the next guide to connect this target cluster into Zora.

Before using this kubeconfig, you can verify that it is functional by running:

kubectl --kubeconfig zora-view-kubeconfig.yml get all --all-namespaces