getporter / kubernetes-mixin

A Kubernetes mixin for Porter

kubernetes Mixin for Porter

This is a kubernetes mixin for Porter. It executes the appropriate helm command based on which action it is included within: install, upgrade, or delete.

Install or Upgrade

porter mixin install kubernetes

Install or Upgrade canary version

porter mixin install kubernetes --version canary --url https://cdn.porter.sh/mixins/kubernetes

Install or Upgrade from feed-url

porter mixin install kubernetes --feed-url https://cdn.porter.sh/mixins/atom.xml

Manually Install or Upgrade with a specific version from github

porter mixin install kubernetes --version $VERSION --url https://github.com/getporter/kubernetes-mixin/releases/download

Mixin Configuration

Kubernetes client version

You can use the clientVersion field to specify the kubectl CLI version.

- kubernetes:
    clientVersion: v1.20.13 # Replace this value with the latest patched version of kubectl

Mixin Actions Syntax

Install Action

install:
  - kubernetes:
      description: "Install Hello World App"
      manifests:
        - /cnab/app/manifests/hello
      wait: true

Upgrade Action

upgrade:
  - kubernetes:
      description: "Upgrade Hello World App"
      manifests:
        - /cnab/app/manifests/hello
      wait: true

Uninstall Action

uninstall:
  - kubernetes:
      description: "Uninstall Hello World App"
      manifests:
        - /cnab/app/manifests/hello
      wait: true

\* Uninstall automatically applies the --ignore-not-found flag so that you can safely repeat the uninstall action without errors.

Outputs

The mixin supports extracting resource metadata from Kubernetes as outputs.

outputs:
    - name: NAME
      resourceType: RESOURCE_TYPE
      resourceName: RESOURCE_TYPE_NAME
      namespace: NAMESPACE
      jsonPath: JSON_PATH_DEFINITION

kubernetes-mixin's Issues

kubernetes mixin should allow uninstall step to succeed when resources are not found

Synopsis

In the uninstall action the kubernetes mixin should be able to handle situations where resources are not found in a graceful manner.

Reasoning

Attempting to recover from a failed bundle installation using uninstall can be almost impossible. If the step creating the k8s resource hasn't been executed the uninstall of said resources will fail hard.

Proposed solution

Add a boolean ignore-not-found property to the uninstall step that adds --ignore-not-found=<value> to the executed command.
That would allow users of the mixin to have uninstall steps that will succeed even if the resource is gone (or have never been there)

Print manifest contents when --debug was passed

Sometimes I get an error about how the manifest is malformed. When that happens it's super hard to troubleshoot. If the kubernetes plugin would print the manifests contents, that would help.

If we run the following command before apply, we can get the rendered manifest printed out when --debug is set.

kubectl apply -f FILE --dry-run=client -o yaml

I checked and if we just specify -o yaml, it won't print the manifest until after its run, so when there's a problem with it, you can't see the file contents. So doing two commands, first dry-run, then apply, in debug mode would give you enough info to figure out what went wrong hopefully.

Download the kubectl client binary dynamically at runtime

Is your feature request related to a problem? Please describe.
I don't always know the version of the kubernetes cluster that I am connecting to at build time.

Describe the solution you'd like
I want the kubernetes mixin to dynamically download the kubectl client binary at runtime if the versions don't match (controlled by a config flag). The helm mixin does this already minus the configuration to bypass this functionality.

Describe alternatives you've considered
N/A

Additional context
You can use the built-in kubectl client to call kubectl version to get the server version, read the json and then download a different kubectl client.

Update example with how to set credentials for kubeconfig

We don't call out that the kubeconfig should be in /home/nonroot/.kube/config or how to use the kubeconfig flag. Let's do that and add an example bundle (or link to one) so people have a working example.

chore: Upgrade to Go 1.20.6

kuberentes mixin should be able to reference a URL

The kuberentes mixin should be able to reference a manifest from a canonical source, like a URL. Then during porter build, the mixin should handle copying the manifest from that source to the invocation image so that it is in the bundle and then at runtime, the mixin uses the cached file instead of the URL.

We don't yet have a solution for how to reference the file at runtime. See getporter/porter#218 and getporter/porter#621 for context which both are intended to provide generic solutions for mixins to these problems.

kubectl command unable to execute

Problem:
mixin seems to be having issues running kubectl commands even after seeing credential set. i can see it's pulling the address from my kubeconfig (see 127.0.0.1:64084) and kubectl runs fine outside of porter

recreation steps:
step 1 & 2 of https://getporter.org/operator/quickstart/
I create a kind cluster, and set kind context. When setting the kubeconfig I set it as a filepath with my full path, not relative.

here's some output:

docker ps
CONTAINER ID   IMAGE                  COMMAND                  CREATED         STATUS         PORTS                       NAMES
   mongo:4.0-xenial       "docker-entrypoint.s…"   4 minutes ago   Up 4 minutes   0.0.0.0:27018->27017/tcp    porter-mongodb-docker-plugin
   kindest/node:v1.26.3   "/usr/local/bin/entr…"   15 hours ago    Up 6 minutes   127.0.0.1:64084->6443/tcp   kind-control-plane

kubeconfig

apiVersion: v1
clusters:
- cluster:
    certificate-authority-data:==
    server: https://127.0.0.1:63373
  name: kind-new-cluster
- cluster:
    certificate-authority-data: 
    server: https://127.0.0.1:64084
  name: kind-kind
contexts:
- context:
    cluster: kind-new-cluster
    user: kind-new-cluster
  name: kind-new-cluster
- context:
    cluster: kind-kind
    user: kind-kind
  name: kind-kind
current-context: kind-kind

porter install porterops -c porterops -r ghcr.io/getporter/porter-operator:v0.8.0

executing install action from porter-operator (installation: /porterops)
Set manager image reference
Setting manager image to ghcr.io/getporter/porter-operator@sha256:dd8d95c853738954781bc1dce62e66d74f51c12eb3aa6536843f268f6f740ec6
Apply operator manifests
The connection to the server 127.0.0.1:64084 was refused - did you specify the right host or port?
Error: error running command /cnab/app/usr/local/bin/kubectl apply -f manifests/operator.yaml --wait: exit status 1
1 error occurred:
	* mixin execution failed: package command failed /cnab/app/cnab/app/mixins/kubernetes/runtimes/kubernetes-runtime install
The connection to the server 127.0.0.1:64084 was refused - did you specify the right host or port?
Error: error running command /cnab/app/usr/local/bin/kubectl apply -f manifests/operator.yaml --wait: exit status 1



1 error occurred:
	* mixin execution failed: package command failed /cnab/app/cnab/app/mixins/kubernetes/runtimes/kubernetes-runtime install
The connection to the server 127.0.0.1:64084 was refused - did you specify the right host or port?
Error: error running command /cnab/app/usr/local/bin/kubectl apply -f manifests/operator.yaml --wait: exit status 1



1 error occurred:
	* container exit code: 1, message: <nil>

(locally, outside porter)

kubectl get pods -A
NAMESPACE            NAME                                         READY   STATUS    RESTARTS        AGE
kube-system          coredns-787d4945fb-2m99d                     1/1     Running   1 (7m37s ago)   14h
kube-system          coredns-787d4945fb-nw87v                     1/1     Running   1 (7m37s ago)   14h
kube-system          etcd-kind-control-plane                      1/1     Running   1 (7m37s ago)   14h
kube-system          kindnet-jnt5g                                1/1     Running   1 (7m37s ago)   14h
kube-system          kube-apiserver-kind-control-plane            1/1     Running   1 (7m37s ago)   14h
kube-system          kube-controller-manager-kind-control-plane   1/1     Running   1 (7m37s ago)   14h
kube-system          kube-proxy-xcd2h                             1/1     Running   1 (7m37s ago)   14h
kube-system          kube-scheduler-kind-control-plane            1/1     Running   1 (7m37s ago)   14h
local-path-storage   local-path-provisioner-75f5b54ffd-z9nkx      1/1     Running   1 (7m37s ago)   14h

Put in place (azure devops) CI to run build/tests against PRs and publishing from main or tag

Create a PR to add the Kubernetes mixin feed into porter-packages

Update any docs accordingly

Make sure the main branch is stable/working as intended

Set up the feed and create a PR to update the porter main feed

kubernetes mixin should have a namespace-create command, that's an upsert

There should be a feature that implements kubectl create ns <foo> but tests first to see whether it exists and only then creates it if not; else returns success immediately.

Cut release from main when it is ready

Add associated docs (CONTRIBUTING, REVIEWING, CODE_OF_CONDUCT)

Control dynamic kubectl download

There are a few cases where dynamically downloading the kubectl client may not be what the bundle author desired and we should make it controllable by them:

• kubectl is backwards compatible. When the bundle has a more recent version of kubectl, there isn't a reason to download an older version to match.
• There may be bug fixes in newer patch versions of kubectl so matching down to the patch isn't always a great behavior when what we really need is API compatibility.
• The bundle may be self-contained and not want to reach out to external resources, perhaps a thick bundle, and attempts to dynamically download the client should be strictly disabled.

Based on this (please add more in the comments below as you see them), I propose that we add the following configuration to the mixin:

mixins:
- kubernetes
     dynamicDownload:
       versionMatch: exact | minor
       useBackwardsCompatible: true
       disabled: true

• dynamicDownload: Defines the behavior of the dynamic kubectl client download
  • versionMatch: Defines how the api server version is compared to the client version to determine whether or not a different client should be downloaded. Defaults to minor.
    A download is triggered when:
    • exact - The versions do not match exactly.
    • minor - The Major.Minor versions do not match. The patch version is allowed to be different.
  • useBackwardsCompatible - When the client is newer than the server, take advantage of the kubectl backwards compatibility guarantee and do not download an older client. Defaults to true. (I tried to make a name that worked well for defaulting to false and couldn't come up with one)
  • disabled: Specifies if the dynamic download feature is disabled. Defaults to false.

With the defaults someone who doesn't customize the config settings will only download a client when the server is a newer Major.Minor version. What do you think?

Add build badge

Add build badge to the top of the README.

Pipeline is: https://dev.azure.com/getporter/porter/_build?definitionId=9