Understanding evroc's cloud API

This document gives context for advanced users seeking to integrate with evroc's cloud using its API.

This document assumes you have run through the Getting Started docs for how to download and log in to the CLI. It assumes that you therefore have a kubeconfig file at ~/.evroc/config.yaml which the CLI login procedure will give you.

It also assumes you have a kubectl installed as well as a solid grasp of kubernetes concepts.

Using kubernetes' API directly

Assuming you have kubectl installed, and have logged into evroc's cloud, you can run e.g.

$ kubectl --kubeconfig=/home/amuller/.evroc/config.yaml get virtualmachines.compute.evroclabs.net
NAME       READY   REASON   VIRTUALMACHINESTATUS   IP          PUBLIC IP
exmaplevm  True    Ready    Running                10.0.0.50

Use the API reference to see the full list of resources you can view in this way.

Namespaces and the kubernetes cluster APIs.

evroc's cloud is built on top of Kubernetes. This means all management requests to create, read, update, list or delete resources in evroc's cloud end up taking the form of a Kubernetes request.

Different resource groups actually correspond to different kubernetes cluster endpoints and are isolated from each other.

When you first get started, an organisation will be created for you, and you can create resources in this organisation using the kubernetes cluster URL of https://kcp.prod.evroclabs.net/clusters/root:<Organization Name>.

When connected to this URL, users of the API are not able to view namespaces. We recommend when you define Kubernetes resources you leave off the namespace from your specifications. If you want to place resources into separate namespaces, we recommend you create different resource groups.

If you want to specify the namespace of resources for some reason, then do NOT use default, instead the correct name of the namespace is the name of your organization.

If you create a resource group, then you will be given a different Kubernetes cluster URL of e.g. https://kcp.prod.evroclabs.net/clusters/root:<Organization Name>/exampleResourceGroup. If you want to specify the namespace of resources for some reason, then do NOT use default, instead the correct name of the namespace when inside a child resource group is the name of your resource group (e.g. exampleResourceGroup).

Resource Groups and Kubernetes Cluster APIs

All evroc resources live inside resource groups. A top level resource group is created for the overall org. Additional resource groups can be created to segregate resources between internal teams of the org.

For example, imagine a company called corveco uses evroc's cloud and has a top-level organization called org-corveco which results in a top level resource group being created. corveco can create nested resource groups for finance and engineering to enable these teams to operate independently within the context of the overall org.

evroc's cloud is built on top of Kubernetes. This means all management requests to create, read, update, list or delete resources in evroc's cloud end up taking the form of a Kubernetes request.

Understanding evroc's cloud

In the above diagram, we see that regardless of whether we use evroc's web console, the evroc CLI or Kubernetes directly, all requests (shown above in pink) are Kubernetes requests. These requests are sent to an API server, which will have a url of the form: https://kcp.prod.evroclabs.net/clusters/root:<Organization Name>/<Path to resource group>

So for example, a request to add a new virtual machine to the engineering resource group would include sending a request to https://kcp.prod.evroclabs.net/clusters/root:org-corveco/engineering URL, but if they wanted to add a new storage bucket for their finance team, the request would need to go to the https://kcp.prod.evroclabs.net/clusters/root:org-corveco/finance URL.

If they wanted to create a sub-team of finance for domestic affairs called domestic, and add a VM in that resource group they would need to:

  1. Create a new resource group inside the finance group, by speaking to the https://kcp.prod.evroclabs.net/clusters/root:org-corveco/finance URL and creating a resource of type iam.evroclabs.net/v1alpha3 Resource Group
  2. Instantiate a new Kubernetes client to the new https://kcp.prod.evroclabs.net/clusters/root:org-corveco/finance/domestic URL
  3. Create a VM by sending a request to the https://kcp.prod.evroclabs.net/clusters/root:org-corveco/finance/domestic URL