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

# kublr/kublr-api

Kublr is an enterprise Kubernetes management platform that enables organizations to centrally deploy,
run, and manage Kubernetes clusters across multiple environments with a comprehensive container management
platform that finally delivers on the Kubernetes promise. Optimized for large enterprises, Kublr is
designed to provide multi-cluster deployments and observability.
Kublr Documentation - https://docs.kublr.com


## Commands

### auth

Authenticate in Kublr Control Plane. Kublr endpoint, username, and password should be configuered in KUBLR_ENDPOINT, KUBLR_USERNAME, and KUBLR_PASSWORD env vars (normally configured via contexts). Kublr API authentication token will be stored in KUBLR_TOKEN environment variable, or refreshed if necessary. Optionally the names of the environment variables may be overriden in the parameters.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kublr-endpoint` | env_var_name | KUBLR_ENDPOINT | Kublr Control Plane URL (MUST NOT include trailing slash), e.g. 'https://my-kublr-kcp.my-org.com' |
| `kublr-username` | env_var_name | KUBLR_USERNAME | Kublr Control Plane Username |
| `kublr-password` | env_var_name | KUBLR_PASSWORD | Kublr Control Plane Password |
| `kublr-token` | env_var_name | KUBLR_TOKEN | Kublr Control Plane Password |
| `insecure` | boolean | false | Do not check ssl certificate for https requests to kublr API |

### call

Call Kublr API given an HTTP method (GET, POST, DELETE etc), API URL path ('/api/meta/version' by default), and optionally data to send (e.g. Kublr Kubernetes JSON cluster specification document). The command relies on Kublr API authentication token available in KUBLR_TOKEN env var; you can use 'auth' command to get or refresh it.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kublr-endpoint` | env_var_name | KUBLR_ENDPOINT | Kublr Control Plane URL |
| `kublr-token` | env_var_name | KUBLR_TOKEN | Kublr Control Plane Password |
| `call-method` | string | GET | Method to use when calling API (GET, POST, DELETE etc) |
| `call-path` | string | /api/meta/version | API path to call |
| `call-data-file` | string |  | File with data to send with a call, e.g. JSON cluster spec for cluster creation call. |
| `result-env-var` | string |  | Env var to use to save result (none if empty) |
| `result-file` | string |  | File to save the result to (none if empty) |
| `insecure` | boolean | false | Do not check ssl certificate for https requests to kublr API |

### get-cluster-config

Retrieve a kubectl config file for a Kublr Kubernetes cluster and configure it for use by kubectl tool. The config is saved in a file and KUBECONFIG environment variable is set correspondingly. The command relies on Kublr API authentication token available in KUBLR_TOKEN env var; you can use 'auth' command to get or refresh it.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kublr-space` | string | default | Kublr space name |
| `kublr-cluster` | string |  | Kublr cluster name |
| `kubeconfig-env-var` | env_var_name | KUBECONFIG | Env var for Kubernetes config path (set to empty if need not be set) |
| `kubeconfig-file` | string | config | File for Kubernetes config |
| `insecure` | boolean | false | Do not check ssl certificate for https requests to kublr API |

### get-kubernetes-client

Get current kubernetes version from kublr configuration and download a kubernetes client (kubectl) from official site. The version is saved to KUBEVER environment (by default) and download client to file "kubectl". The command relies on Kublr API authentication token available in KUBLR_TOKEN env var; you can use 'auth' command to get or refresh it.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kublr-space` | string | default | Kublr space name |
| `kublr-cluster` | string |  | Kublr cluster name |
| `kubever-env-var` | env_var_name | KUBEVER | Env var for Kubernetes version |
| `kubectl-file` | string | kubectl | File for Kubernetes config |
| `insecure` | boolean | false | Do not check ssl certificate for https requests to kublr API |

### create-cluster

Creates cluster by json spec using API.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `kublr-space` | string | default | Kublr space name |
| `kublr-cluster` | string |  | Kublr cluster name |
| `kubever-env-var` | env_var_name | KUBEVER | Env var for Kubernetes version |
| `kubectl-file` | string | kubectl | File for Kubernetes config |
| `insecure` | boolean | false | Do not check ssl certificate for https requests to kublr API |

## Examples

### simple_authentication

Authenticate with Kublr API with API endpoint, username, and password in KUBLR_ENDPOINT, KUBLR_USERNAME, and KUBLR_PASSWORD env vars correspondingly. Normally you would set these environment variables via CircleCI contexts. Resulting authentication token is stored in KUBLR_TOKEN env var.


```yaml
version: 2.1
orbs:
  kublr-api: kublr/kublr-api@dev
jobs:
  build:
    docker:
      - image: circleci/node:9.9.0
    steps:
      - kublr-api/auth
```

### parameterized_authentication

Authenticate with Kublr API with non-default API endpoint, username, password, and resulting token env var names passed directly.


```yaml
version: 2.1
orbs:
  kublr-api: kublr/kublr-api@dev
jobs:
  build:
    docker:
      - image: circleci/node:9.9.0
    steps:
      - kublr-api/auth:
          kublr-endpoint: KUBLR_DEV_ENDPOINT
          kublr-username: KUBLR_DEV_USERNAME
          kublr-password: KUBLR_DEV_PASSWORD
          kublr-token: KUBLR_DEV_TOKEN
```

### api_call

Call Kublr API with specified HTTP method, path, and optionally input data. The method assumes that authenticaiton is already performed and the token is stored in KUBLR_TOKEN env var.


```yaml
version: 2.1
orbs:
  kublr-api: kublr/kublr-api@dev
jobs:
  build:
    docker:
      - image: circleci/node:9.9.0
    steps:
      - kublr-api/auth
      - kublr-api/call:
          call-method: DELETE
          call-path: /api/spaces/my-space/cluster/my-cluster
```

### get_and_configure_kubernetes_config

Acquire Kubernetes config via Kublr API, save it in a file and configure it for use with kubectl. The method assumes that authenticaiton is already performed and the token is stored in KUBLR_TOKEN env var.


```yaml
version: 2.1
orbs:
  kublr-api: kublr/kublr-api@dev
jobs:
  build:
    docker:
      - image: circleci/node:9.9.0
    steps:
      - kublr-api/auth
      - kublr-api/get-cluster-config:
          kublr-space: demo
          kublr-cluster: aws-demo
      - run: |
          echo "Kubernetes config in '${KUBECONFIG:-}' file:"
          cat "${KUBECONFIG:-}"
      - run:
          name: Setup kubectl
          command: >-
            curl
            https://storage.googleapis.com/kubernetes-release/release/v1.10.7/bin/linux/amd64/kubectl
            > kubectl && chmod a+x kubectl
      - run:
          name: Test kubectl with kubeconfig
          command: ./kubectl get nodes
```

### full_example

This example shows full sequence of operations with Kublr control plane: authentication, API calls (possibly including Kubernetes cluster creation, status checks, deletion etc), acquisition of Kubernetes cluster config file, and download, setup, and using kubectl tool. Authentication with Kublr API relies on the API endpoint, username, and password provided in KUBLR_ENDPOINT, KUBLR_USERNAME, and KUBLR_PASSWORD env vars correspondingly. Normally you would set these environment variables via CircleCI contexts.


```yaml
version: 2.1
orbs:
  kublr-api: kublr/kublr-api@dev
jobs:
  build:
    docker:
      - image: circleci/node:9.9.0
    steps:
      - checkout
      - kublr-api/auth
      - run:
          name: Print Kublr API token
          command: echo "KUBLR_TOKEN=${KUBLR_TOKEN:-}"
      - kublr-api/call:
          result-env-var: KUBLR_VERSION_JSON
          result-file: kublr-version.json
      - run:
          name: Print Kublr API call results stored in an env var
          command: echo "KUBLR_VERSION_JSON=${KUBLR_VERSION_JSON:-}"
      - run:
          name: Print Kublr API call results stored in a file
          command: cat kublr-version.json
      - kublr-api/get-cluster-config:
          kublr-space: demo
          kublr-cluster: aws-demo
      - run:
          name: Print KUBECONFIG env var
          command: echo "KUBECONFIG=${KUBECONFIG:-}"
      - run:
          name: Print Kubernetes config file content
          command: |
            echo "Kubernetes config in '${KUBECONFIG:-}' file:"
            cat "${KUBECONFIG:-}"
      - kublr-api/get-kubernetes-client:
          kublr-space: demo
          kublr-cluster: aws-demo
      - run:
          name: Run kubectl command
          command: ./kubectl get nodes
```