The Radix API is an HTTP server for accessing functionality on the Radix platform. This document is for Radix developers, or anyone interested in poking around. Please see Development practices for more information on the release process.
The Radix API is meant to be the single point of entry for platform users to the platform (through e.g. the Web Console). Users should not be able to access the Kubernetes API directly; therefore the Radix API limits and customises what platform users are able to do.
Authentication and authorisation are performed through an HTTP bearer token, which is (in most cases) relayed to the Kubernetes API. The Kubernetes AAD integration then performs its authentication and resource authorisation checks, and the result is relayed to the the user.
Some requests trigger more complex authorisation checks within the Radix API itself by using the
You need Go installed. Make sure
GOROOT are properly set up.
go-swagger(on a Mac, you can install it with Homebrew:
brew install go-swagger)
go get github.com/rakyll/statik)
Clone the repo into your
GOPATH and run
go mod download.
Dependencies - go modules
Go modules are used for dependency management. See link for information how to add, upgrade and remove dependencies. E.g. To update
- list versions:
go list -m -versions github.com/equinor/radix-operator
go get email@example.com
The following env vars are needed. Useful default values in brackets.
You also probably want to start with the argument
--useOutClusterClient=false. If this is set to
true (the default) the program will connect to the K8S API host defined by the
K8S_API_HOST env var and will require auth tokens in all client requests. Set to
false, a service principal with superpowers is used to authorise the requests instead (you still need to send a
bearer whatever auth header with the requests, but its value is ignored).
false, the Radix API will connect to the currently-configured
If you are using VSCode, there is a convenient launch configuration in
Common errors running locally
panic: statik/fs: no zip data registered
We follow the semantic version as recommended by go.
radix-api has three places to set version
docs/docs.go - API version, used in API’s URL
docs/docs.go - indicates changes in radix-api logic - to see (e.g in swagger), that the version in the environment corresponds with what you wanted
Run following command to update version in `swagger.json` ``` make swagger ```
tagin git repository (in
masterbranch) - matching to the version of
Run following command to set
tag(with corresponding version)
git tag v1.0.0 git push origin v1.0.0
Manual redeployment on existing cluster
- Install draft (https://draft.sh/)
draft initfrom project directory (inside
draft config set registry radixdev.azurecr.io
az acr login --name radixdev
- Update version
draft upto install to dev environment of radix-api
- Wait for pods to start
- Go to
https://server-radix-api-dev.<cluster name>.dev.radix.equinor.com/swaggerui/to see if the version in the swagger corresponds with the version you set in the header.
The Radix API server is meant to be the single point of entry for platform users to the platform (through the web console or a command line interface). They should not be able to access the Kubernetes API directly. Therefore the Radix API will limit what platform users will be able to do. Authentication is done through a bearer token, which essentially is relayed to the Kubernetes API to ensure that users only can see what they should be able to see, and therefore rely on the k8s AAD integration for authentication 1.
1 Until the work referred to in this document is solved, listing applications, listing jobs and creating build job is done using the service account of the API server, and access is therefore verified inside the Radix API server rather than by the Kubernetes API using RBAC.
Radix API follows the standard procedure defined in how we work.
Radix API is installed as a Radix application in script when setting up a cluster. It will setup API environment with aliases, and a Webhook so that changes to this repository will be reflected in Radix platform.
If radix-operator is updated to a new tag, `go.mod` should be updated as follows: github.com/equinor/radix-operator <NEW_OPERATOR_TAG>