> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# devopsspiral/k3d

Orb for creating and using kubernetes cluster in your pipelines. Based on K3d/K3s project.


## Commands

### k3d-down

Destroy k8s (k3d/k3s) cluster

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string | myk3d | Name for the k3d cluster |

### k3d-helpers

Helpers to make k3d usage easier

### k3d-run

Wrapper around run command with helpers included

| Parameter | Type | Default | Description |
|---|---|---|---|
| `command` | string | k3d --version
helm version
kubectl version
 | Command using docker, k3d, helm, kubectl |
| `step-name` | string |  | Name of the run step |

### k3d-up

Starts k8s (k3d/k3s) cluster

| Parameter | Type | Default | Description |
|---|---|---|---|
| `agents` | integer | 1 | Number of agents |
| `cluster-name` | string | myk3d | Name for the k3d cluster |
| `k3s-bin-version` | string | v4.0.0 | K3s binary version (currently > v4.0.0 is not supported) |
| `k3s-version` | string | latest | Image tag of K3s container (determines k8s version) |

### k3d-use

Switches context to particular cluster

| Parameter | Type | Default | Description |
|---|---|---|---|
| `cluster-name` | string | myk3d | Name for the k3d cluster |

## Executors

### default

This is base docker executor that all other language specific executors inherits.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `tag` | string | 2020.01 | Pick a specific image variant: https://github.com/CircleCI-Public/cimg-base#tagging-scheme
 |

## Examples

### api-reaching

Build own container and deploy on k8s


```yaml
jobs:
  test-k8s-api-reaching:
    executor: k3d/default
    steps:
      - setup_remote_docker
      - checkout
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: >
            # This is exactly how helm and kubectl is used in this orb reaching
            to 0.0.0.0:6443

            docker run --rm -it --name kubectl -e KUBECONFIG=$K3D_KUBECONFIG \

            --network container:k3d-${K3D_CLUSTER}-serverlb \

            --volumes-from kubeconfig bitnami/kubectl get pods | grep 'No
            resources found'
          step-name: Reach K8s API directly
orbs:
  k3d: devopsspiral/k3d@0.1.0
version: 2.1
workflows:
  main:
    jobs:
      - test-k8s-api-reaching
```

### expose-via-ingress

Expose service via ingress


```yaml
jobs:
  test-k3d-expose-via-ingress:
    executor: python/default
    steps:
      - setup_remote_docker
      - checkout
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: >
            helm repo add stable https://charts.helm.sh/stable

            # Notice repo content available at /repo/ automatically

            helm install grafana stable/grafana -f
            /repo/sample/grafana/with_ingress.yaml

            sleep 45

            export INGRESS_IP=$(kubectl get ing --namespace default grafana -o
            jsonpath='{.status.loadBalancer.ingress[0].ip}')

            # Test if Grafana login page is reachable, exit code 1 means grep
            didn't found match

            docker run --rm -it --network k3d-${K3D_CLUSTER} busybox \

            /bin/sh -c "echo '${INGRESS_IP}  chart-example.local' >> /etc/hosts;
            \

            wget http://chart-example.local/; cat index.html" | grep Grafana
          step-name: Expose service via ingress
orbs:
  k3d: devopsspiral/k3d@0.1.0
  python: circleci/python@0.3.2
version: 2.1
workflows:
  main:
    jobs:
      - test-k3d-expose-via-ingress
```

### expose-via-lb

Expose service via loadbalancer


```yaml
jobs:
  test-k3d-expose-via-lb:
    executor: python/default
    steps:
      - setup_remote_docker
      - checkout
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: >
            helm repo add stable https://charts.helm.sh/stable

            # Notice repo content available at /repo/ automatically

            helm install grafana stable/grafana -f /repo/grafana/with_lb.yaml

            sleep 30

            export SERVICE_IP=$(kubectl get svc --namespace default grafana -o
            jsonpath='{.status.loadBalancer.ingress[0].ip}')

            # Test if Grafana login page is reachable, exit code 1 means grep
            didn't found match

            docker run --rm -it --network k3d-${K3D_CLUSTER} busybox /bin/sh -c
            "wget ${SERVICE_IP}:3000; cat index.html" | grep Grafana
          step-name: Expose service via loadbalancer
orbs:
  k3d: devopsspiral/k3d@0.1.0
  python: circleci/python@0.3.2
version: 2.1
workflows:
  main:
    jobs:
      - test-k3d-expose-via-lb
```

### expose-via-proxy

Expose service via kubectl proxy


```yaml
jobs:
  test-k3d-expose-via-proxy:
    executor: python/default
    steps:
      - setup_remote_docker
      - checkout
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: >
            helm repo add stable https://charts.helm.sh/stable

            helm install grafana stable/grafana

            sleep 30

            export POD_NAME=$(kubectl get pods --namespace default -l
            "app.kubernetes.io/name=grafana,app.kubernetes.io/instance=grafana"
            -o jsonpath="{.items[0].metadata.name}")

            proxy --namespace default port-forward $POD_NAME 3000

            docker run --rm -it --network container:proxy busybox /bin/sh -c
            "wget 0.0.0.0:3000; cat index.html" | grep Grafana
          step-name: Expose service via kubectl proxy
orbs:
  k3d: devopsspiral/k3d@0.1.0
  python: circleci/python@0.3.2
version: 2.1
workflows:
  main:
    jobs:
      - test-k3d-expose-via-proxy
```

### own-image

Build own container and deploy on k8s


```yaml
jobs:
  test-k3d-expose-own-image:
    executor: k3d/default
    steps:
      - setup_remote_docker
      - checkout
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: >
            docker build -t pyserver -f sample/own_image/Dockerfile .

            k3d image import -c circleci-k8s-1 pyserver:latest

            # use imagePullPolicy: Never

            kubectl apply -f /repo/sample/own_image/

            sleep 15

            export SERVICE_IP=$(kubectl get svc --namespace default
            pyserver-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')

            # Test if service is exposed

            docker run --rm -it --network k3d-${K3D_CLUSTER} busybox /bin/sh -c
            "wget ${SERVICE_IP}:9000; cat index.html"
          step-name: Build own container and deploy on k8s
orbs:
  k3d: devopsspiral/k3d@0.1.0
version: 2.1
workflows:
  main:
    jobs:
      - test-k3d-expose-own-image
```

### switching-clusters

Pass K3s, helm and kubectl versions


```yaml
jobs:
  test-switching-clusters:
    executor: k3d/default
    steps:
      - setup_remote_docker
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
          k3s-version: v1.16.15-k3s1
      - k3d/k3d-up:
          cluster-name: circleci-k8s-2
          k3s-version: v1.16.10-k3s1
      - k3d/k3d-up:
          agents: 3
          cluster-name: circleci-k8s-3
          k3s-version: v1.17.12-k3s1
      - k3d/k3d-run:
          command: |
            # Orb by default is using most recently created cluster,
            # so no need to k3d-use to use circleci-k8s-3 cluster
            kubectl version | grep 'v1.17.12+k3s1'
          step-name: Check versions
      - k3d/k3d-use:
          cluster-name: circleci-k8s-2
      - k3d/k3d-run:
          command: |
            kubectl version | grep 'v1.16.10+k3s1'
          step-name: Check versions
      - k3d/k3d-use:
          cluster-name: circleci-k8s-1
      - k3d/k3d-run:
          command: |
            kubectl version | grep 'v1.16.15+k3s1'
          step-name: Check versions
orbs:
  k3d: devopsspiral/k3d@0.1.0
version: 2.1
workflows:
  main:
    jobs:
      - test-switching-clusters
```

### versions

Pass K3s, helm and kubectl versions


```yaml
jobs:
  test-k3d-versions:
    environment:
      - KUBECTL_VERSION: 1.16.15
      - HELM_VERSION: 3.3.1
    executor: k3d/default
    steps:
      - setup_remote_docker
      - k3d/k3d-helpers
      - k3d/k3d-up:
          cluster-name: circleci-k8s-1
          k3s-version: v1.16.14-k3s1
      - k3d/k3d-run:
          command: |
            k3d --version
            helm version | grep 'v3.3.1'
            # Client version
            kubectl version | grep '1.16.15'
            # Server version
            kubectl version | grep '1.16.14+k3s1'
          step-name: Check versions
orbs:
  k3d: devopsspiral/k3d@0.1.0
version: 2.1
workflows:
  main:
    jobs:
      - test-k3d-versions
```