Direct Kubernetes access with kubectl

kubectl is the CLI for directly inspecting and editing your workloads in Kubernetes.

Danger zone

Do not rely on being able to access your apps using kubectl. kubectl access is provided as a workaround while we improve servicability though the CLI, API and website.

One of the main motivations for building HOPS was to let you avoid dealing with Kubernetes's complexity. But here we are - you're about to do just that. You can read more about our Kubernetes environment here.

We wish you did not have to follow this how-to. If you're in the unfortunate position where this is the only way to do what you're trying to accomplish, reach out to us, we're interested in hearing about your use case.

Returning users: Jump to Logging in again

Get access to the Kubernetes cluster

HOPS' access controls are configured in the access.toml-file in the iterapp-config repository.

  1. Add an entry for the project you wish to access in the access.toml file. The entry has the following format:

    [namespaces.{{ Namespace }}]
edit = ["{{ iterate.no Google account}}"]

    The namespace format is described in our Kubernetes reference.

  2. Ask someone in #ops on Slack to apply the changes. (The documentation for syncing is in the same repo).

    (If you have a problem getting access to the app-iterate-project, you are probably not added to the all-no@iterate.no email. #ops can fix that.)

Install and configure the gcloud CLI

kubectl uses credentials on your computer to authenticate with the Kubernetes cluster. You need to set up these credentials. In Google Cloud, Kubernetes credentials are created using the gcloud CLI.

  1. Install gcloud, either:

    a. by using brew on macOS :

    $ brew install --cask google-cloud-sdk

    NB: You might have to add gcloud to your PATH. Run brew info google-cloud-sdk and follow the caveats section.

    b. by following the instructions on Google Cloud's developer documentation site.

  2. Verify that gcloud works, and that it returns version information:

    $ gcloud version

  3. We highly recommend you create a configuration for this purpose. In a bash or zsh shell:

    # Set this first:
export ITERAPP_USERNAME=SET_YOUR_USERNAME@iterate.no

# Copy this entire thing:
sh -i -s <<'EOF'
    set -ux;
    # This creates a new configuration
    gcloud config configurations create hops-iterate || true;

    # The following configures the configuration.
    # Project does not refer to your app. It refers to which Google Cloud project the
    # cluster belongs to. Do not change this value.
    gcloud config set project "app-iterate" || true;
    gcloud config set account "$ITERAPP_USERNAME" || true;
    gcloud config set compute/zone "europe-west1-d" || true;
    gcloud config set compute/region "europe-west1" || true;
    gcloud config set container/cluster "iterapp-gke" || true;
EOF

  4. We'll use gcloud later to finish configuring kubectl.

Install kubectl and the credential helpers

  1. Install kubectl. This is the primary Kubernetes interface.

  2. Verify that kubectl works, and that it returns version information:

    $ kubectl version

  3. Install gke-gcloud-auth-plugin. This is an authentication helper which provides kubectl with valid credentials for the Kubernetes cluster. We'll create these credentials using the gcloud CLI later on.

    Install the plugin using gcloud:

    $ gcloud components install gke-gcloud-auth-plugin

  4. Verify that gke-gcloud-auth-plugin works, and that it returns version information:

    $ gke-gcloud-auth-plugin --version

Configuring kubectl for the HOPS cluster

  1. Create a context for the HOPS cluster ("iterapp-gke") for kubectl using gcloud:

    $ gcloud --project=app-iterate \
    container clusters --zone=europe-west1-d \
    get-credentials \
    iterapp-gke

# Output:
# kubeconfig entry generated for iterapp-gke.

  2. Optionally, change the name of the kubectl context that was created:

    $ kubectl config rename-context gke_app-iterate_europe-west1-d_iterapp-gke hops-iterate

# Output:
# Context "gke_app-iterate_europe-west1-d_iterapp-gke" renamed to "hops-iterate".

  3. Finally, verify that your context is present:

    $ kubectl config get-contexts

# Output (truncated):
# CURRENT   NAME           CLUSTER ...
# *         hops-iterate   gke_app-iterate_europe-west1-d_iterapp-gke

Logging in again

Your authentication runs out after 24 hours, after which you need to log back in.

  1. Activate the correct gcloud configuration and log in:

    $ gcloud config configurations activate hops-iterate && gcloud auth login

# Output:
# (...)
# You are now logged in as my.name@iterate.no

  2. Ensure you're in the correct kubectl context:

    $ kubectl config use-context hops-iterate

# Output:
# Switched to context "hops-iterate".

    Errors? Go to Configuring kubectl for the HOPS cluster.

  3. Check if you have access by running a command that lists namespaces.

    $ kubectl get ns