diff --git a/versioned_docs/version-2.8/api/quickstart.md b/versioned_docs/version-2.8/api/quickstart.md new file mode 100644 index 00000000000..4529964d59a --- /dev/null +++ b/versioned_docs/version-2.8/api/quickstart.md @@ -0,0 +1,140 @@ +--- +title: API Quick Start Guide +--- + +You can access Rancher's resources through the Kubernetes API. This guide will help you get started on using this API as a Rancher user. + +1. In the upper left corner, click **☰ > Global Settings**. +2. Find and copy the address in the `server-url` field. +3. [Create](../reference-guides/user-settings/api-keys#creating-an-api-key) a Rancher API key with no scope. + + :::danger + + A Rancher API key with no scope grants unrestricted access to all resources that the user can access. To prevent unauthorized use, this key should be stored securely and rotated frequently. + + ::: + +4. Create a `kubeconfig.yaml` file. Replace `$SERVER_URL` with the server url and `$API_KEY` with your Rancher API key: + + ```yaml + apiVersion: v1 + kind: Config + clusters: + - name: "rancher" + cluster: + server: "$SERVER_URL" + + users: + - name: "rancher" + user: + token: "$API_KEY" + + contexts: + - name: "rancher" + context: + user: "rancher" + cluster: "rancher" + + current-context: "rancher" + ``` + +You can use this file with any compatible tool, such as kubectl or [client-go](https://github.com/kubernetes/client-go). For a quick demo, see the [kubectl example](#api-kubectl-example). + +For more information on handling more complex certificate setups, see [Specifying CA Certs](#specifying-ca-certs). + +For more information on available kubeconfig options, see the [upstream documentation](https://kubernetes.io/docs/tasks/access-application-cluster/configure-access-multiple-clusters/). + +## API kubectl Example + +1. Set your KUBECONFIG environment variable to the kubeconfig file you just created: + + ```bash + export KUBECONFIG=$(pwd)/kubeconfig.yaml + ``` + +2. Use `kubectl explain` to view the available fields for projects, or complex sub-fields of resources: + + ```bash + kubectl explain projects + kubectl explain projects.spec + ``` + +Not all resources may have detailed output. + +3. Add the following content to a file named `project.yaml`: + + ```yaml + apiVersion: management.cattle.io/v3 + kind: Project + metadata: + # name should be unique across all projects in every cluster + name: p-abc123 + # generateName can be used instead of `name` to randomly generate a name. + # generateName: p- + # namespace should match spec.ClusterName. + namespace: local + spec: + # clusterName should match `metadata.Name` of the target cluster. + clusterName: local + description: Example Project + # displayName is the human-readable name and is visible from the UI. + displayName: Example + ``` + +4. Create the project: + + ```bash + kubectl create -f project.yaml + ``` + +5. Delete the project: + + How you delete the project depends on how you created the project name. + + **A. If you used `name` when creating the project**: + + ```bash + kubectl delete -f project.yaml + ``` + + **B. If you used `generateName`**: + + Replace `$PROJECT_NAME` with the randomly generated name of the project displayed by Kubectl after you created the project. + + ```bash + kubectl delete project $PROJECT_NAME -n local + ``` + +## Specifying CA Certs + +To ensure that your tools can recognize Rancher's CA certificates, most setups require additional modifications to the above template. + +1. In the upper left corner, click **☰ > Global Settings**. +2. Find and copy the value in the `ca-certs` field. +3. Save the value in a file named `rancher.crt`. + + :::note + If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated in step 5. + ::: + +4. The following commands will convert `rancher.crt` to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finishing by removing the `rancher.crt` file: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.certificate-authority-data $(cat rancher.crt | base64 -i - | tr -d '\n') + rm rancher.crt + ``` +5. (Optional) If you use self-signed certificatess that aren't trusted by your system, you can set the insecure option in your kubeconfig with kubectl: + + :::danger + + This option shouldn't be used in production as it is a security risk. + + ::: + + ```bash + export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG + kubectl config set clusters.rancher.insecure-skip-tls-verify true + ``` + + If your Rancher instance is proxied by another service, you must extract the certificate that the service is using, and add it to the kubeconfig file, as demonstrated above. diff --git a/versioned_sidebars/version-2.8-sidebars.json b/versioned_sidebars/version-2.8-sidebars.json index 8c30c5f4a13..0e0f3c923c8 100644 --- a/versioned_sidebars/version-2.8-sidebars.json +++ b/versioned_sidebars/version-2.8-sidebars.json @@ -1305,6 +1305,16 @@ } ] }, + { + "type": "category", + "label": "Rancher Kubernetes API", + "items": [ + "api/quickstart", + { + + } + ] + }, "contribute-to-rancher", { "type": "category",