Last modified May 27, 2020

API Access to Giant Swarm Resources

For integrating Giant Swarm with your automation, we provide programmatic access via two different APIs:

In the following sections we explain the differences and specific benefits and provide some guidance on how to get started.

The Rest API

The Rest API is an abstraction over the many resources that reside in the Control Plane of a Giant Swarm installation. It is used by our dedicated user interfaces, the web User Interface and gsctl.

Browse our API documentation for a complete overview into the provided functionality.

The Rest API was originally designed to provide a simpler, easier access to the relevant resources for managing clusters, key pairs, etc. while keeping the internals under the hood. However at Giant Swarm we learnt that there are always more use cases emerging on your side than we could anticipate in our API design. We realized that the best we can do for you to provide full insight into the state and spec of your infrastructure is by opening up the underlying system itself.

With this realization, we made the decision to phase out the development of the Rest API in favor of providing access to the Control Plane Kubernetes API instead.

As of now, there is no termination date for the Rest API. As it might provide the much simpler and more accessible starting point, feel free to explore the documentation, knowing that one day you may have to switch to the Control Plane Kubernetes API.

The Control Plane Kubernetes API (Preview)

What it is

At Giant Swarm, when we say “control plane”, we talk about the Kubernetes Cluster that runs all the operational and monitoring workloads which are needed to create and manage the “tenant clusters”. These are the clusters you create to run your actual workloads. This is not to be confused with how the Kubernetes project uses the same term. In that case, it simply refers to the master nodes of a Kubernetes cluster.

The control plane is a Kubernetes cluster. Your tenant clusters and other associated resources are represented in that cluster as custom resources. To access these, you can use the Kubernetes API of the cluster that forms the control plane, or in short, the Control Plane Kubernetes API.

How to gain access

Access to the Giant Swarm Control Plane API is secured using OIDC. Please contact your Solution Engineer (SE) to sort out the details.

Currently we provide read-only access by default. As we are currently working on a fine-grained way to control permissions to resources, and validation and defaulting are not implemented to the extend we want to, having write access right now means fully unrestricted access and should only be granted to select individuals.

How to use

We recommend using kubectl to navigate the resources present on the Control Plane Kubernetes API.

To facilitate this we’ve been working on a proof of concept kubectl plugin called kubectl-gs. Our goal is to have the same great user experience you’ve become accustomed from gsctl and happa.

Besides general Kubernetes know-how this will require only a bit of structural knowledge:

How we organize resources in namespaces

We create one namespace for each tenant cluster, where the namespace name is equal to the tenant cluster ID. All cluster specific resources reside in the namespace of that tenant cluster.

Which custom resources are used for what purpose

Following are some resources that should help you:

Feedback is welcome

We are keen to learn from you about your experience with using the Control Plane Kubernetes API, with navigating the custom resources via the API, with our reference documentation and the user guides we provide. This helps us provide more and better material and improve to make the journey more seamless, more satisfactory for you.

So please, don’t hesitate to give your feedback in your Slack channel.