RK-API Quick Start Guide
You can access Rancher's resources through the Kubernetes API. This guide helps you get started on using this API as a Rancher user.
In the upper left corner, click ☰ > Global Settings.
Find and copy the address in the
server-url
field.Create a Rancher API key with no scope.
dangerA 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.
Create a
kubeconfig.yaml
file. Replace$SERVER_URL
with the server url and$API_KEY
with your Rancher API key: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. For a quick demo, see the kubectl example.
For more information on handling more complex certificate setups, see Specifying CA Certs.
For more information on available kubeconfig options, see the upstream documentation.
API kubectl Example
In this example, we'll show how to use kubectl to create a project, followed by deleting it. For a list of other Rancher resources available, refer to the API Reference page.
At this time, not all Rancher resources are available through the Rancher Kubernetes API.
Set your KUBECONFIG environment variable to the kubeconfig file you just created:
export KUBECONFIG=$(pwd)/kubeconfig.yaml
Use
kubectl explain
to view the available fields for projects, or complex sub-fields of resources:kubectl explain projects
kubectl explain projects.spec
Not all resources may have detailed output.
Add the following content to a file named
project.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: ExampleCreate the project:
kubectl create -f project.yaml
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: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.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.
In the upper left corner, click ☰ > Global Settings.
Find and copy the value in the
ca-certs
field.Save the value in a file named
rancher.crt
.noteIf 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.
The following commands convert
rancher.crt
to base64 output, trim all new-lines, and update the cluster in the kubeconfig with the certificate, then finish by removing therancher.crt
file: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(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:
dangerThis option shouldn't be used in production as it is a security risk.
export KUBECONFIG=$PATH_TO_RANCHER_KUBECONFIG
kubectl config set clusters.rancher.insecure-skip-tls-verify trueIf 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.