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 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:

   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.

note

At this time, not all Rancher resources are available through the Rancher Kubernetes API.

1. Set your KUBECONFIG environment variable to the kubeconfig file you just created:

   export KUBECONFIG=$(pwd)/kubeconfig.yaml

2. 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.

3. 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: Example

4. Create the project:

   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:

   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.

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:

   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.

   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.