rancher-docs/docs/api/quickstart.md

title

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

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:

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

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.