HTTPS/TLS
How to protect your Controller UI, API, and and Registry API with HTTPS/TLS.
These features are currently only available for our Enterprise
tier customers.
You must have all Nodes licensed with Enterprise or higher for these features to enable.
We highly recommend that HTTPS/TLS is enabled before using any of these features.
We provide several Authentication methods for the Anka Build Cloud. They are split into Human and Programmatic Access.
Authentication features are enabled by adding ANKA_ENABLE_AUTH
to your Controller and/or Registry configuration and setting it to true
.
Each one of these methods requires Root Token Authentication is enabled first.
These methods are available to a human through a browser to the Controller UI/Dashboard.
These methods are available for users and scripts that need to use the Controller API, Registry API, or are using the Anka CLI. They can also be used in our CI Integrations.
ankacluster join --api-*
and anka registry --api-*
optionsankalcluster join --cert
, --cert-key
, etc.Authorization allows you to control access to specific actions/endpoints of the API and even specific Resources like Nodes and Templates in your Controller and Registry. It has four parts to it that are important to understand:
Groups are the wrappers for all Permissions and Resources. You attach a Groups to a Authentication credential to enable certain access.
Resources limit which Nodes and Templates the credential can control.
After a Group is created, you’ll assign it to a specific credential. The credential can have one or more Groups attached and it’s important you consider how much access for each Group you need to provide for your use-case and security requirements.
In this guide we will start with the most common use-case of sharing Node between multiple teams (Groups), then explain how to isolate Nodes per team (similar to how the older Node Groups worked) later on.
To enable Authorization features, you’ll need to ensure:
Authentication is enabled by setting ANKA_ENABLE_AUTH
and ANKA_ROOT_TOKEN
ENVs in your Controller & Registry config. You’re also familiar with one of the existing Authentication methods and have one set up.
Groups + Group Permissions are enabled by enabling Authorization. The following ENVs can be added to your config to achieve this:
ANKA_ENABLE_CONTROLLER_AUTHORIZATION
(boolean) works for both macOS and docker controller packages.ANKA_ENABLE_REGISTRY_AUTHORIZATION
(boolean) works for the macOS registry package only.ANKA_ENABLE_AUTHORIZATION
(boolean) is only for the registry.This should expose the https://<controller address>/#/permission-groups
page in your Controller.
Resource Permissions are enabled by setting ANKA_ENABLE_RESOURCE_MANAGEMENT
to true
in your configuration.
License Considerations: These features are only available for Enterprise tier licenses.
- Enterprise license customers cannot control authorization and each authentication credential will have full access to the system.
- However, Enterprise Plus customers will be able to use Permission Groups and Resources to have more fine-grained control over access.
Do not confuse Node Groups with Groups/Group Permissions.
Under the Permissions section of the Controller UI (https://<controller address>/#/permission-groups
), let’s create a group for our nodes to be able to connect.
Next, create a new group named node
by clicking the [+] button.
You can now target and add specific Permissions or Resources for the Group. Click the circular (💻) icon on the right to highlight what permission should be set for Nodes to communicate with the Controller. Then check/enable the highlighted permissions and click Save Permissions at the bottom of the page. Important: Finally, do the same but under the Registry Component.
Note: We’ll not be setting Resources right now.
Be sure to download the key if you’re creating a new UAK.
You will now see the UAK in the list.
The node certificate now has permissions to perform the specifically set actions against all Resources (if Resource Management is disabled).
❯ sudo ankacluster join http://anka.controller:8090 --api-key-file ~/node.cer --api-key-id "node"
Testing connection to the controller...: Ok
Testing connection to the registry...: Ok
Success!
Anka Cloud Cluster join success
Node Groups are disabled while Resource Management is enabled.
The Resource Management/Permissions feature is enabled by setting ANKA_ENABLE_RESOURCE_MANAGEMENT
to true
in your configuration. Once enabled, it unlocks the Resources tab under /permission-groups.
Within the Resources tab you will be able to, depending on the Component selected, add specific Nodes or Template Resources to the Group. This limits the Group to certain actions that can be performed against those Resources.
An example of this is allowing the iOS team/group to distribute specific Templates to specific Nodes, but not create VM Instances or delete the Node.
In the previous section on Group Permissions, we joined a Node using a credential with the Group node
attached. This Group only has Permissions to perform the minimum required actions to run as an Anka Node and communicate with the Controller. We did not add Resources to it though (even though we technically could) so we can instead have team specific Groups and credentials.
In this example, each team gets only their Node or Template Resources assigned to their Group, with no ability to make API calls to Components/Permissions. Instead, other non-team Groups handle the ability to call certain endpoints and perform certain actions to the Controller and Registry. Individual groups (team and non-team related) are then assigned to certain credential, combining the Permissions and Resources.
It’s important to understand that a single credential, like a UAK or a Certificate, should only ever be used by a single user or client. You wouldn’t ever want to share the Node credential with a team for example. Create a second credential for that team, then in order for the Node to be able to access the team’s credential, add the team’s Group to the Node credential.
Create two groups: ios
and instance-control
.
Under the ios
Group > Resources, add the Template Resource you want this team to access. The bare minimum permissions are seen in the image below.
instance-control
Group > Permissions, add all of the Instances Permissions like in the image below.Now create a new credential (not Group) named service-user
and attach those two groups. We’ll use UAKs for this example. There is no need for the service-user
to have its own group as it will get the VM start and terminate permissions from instance-control
group and Template/Node permissions from the ios
group.
Attach the group ios
to the node
credential we created in the previous section and joined our node with so that that it can also collect information about the Template in order to start the VM Instance properly (it checks the download size of the template before pulling). Your UAK setup should look something like this image.
We can now use the service-user
credential in your CI/CD tools to communicate with the Controller when an ios
team member triggers a job. When the service-user
credential makes an API call to start a VM Instance, it will pass in the ios
group. That ios
group has access to the template being targeted and is required.
The method described above works well for sharing the same nodes amongst all teams in an organization. But what if you want to isolate specific nodes to specific teams? Node Groups are disabled when Resource Management is enabled, but that should make sense to you by now as Node access/permissions are now bound to a specific Group + a specific credential. There are are several other scenarios possible which we’ll detail below.
You cannot have a shared Node credential and also limit by Node Resources for specific teams.
This configuration allows isolating certain Nodes to certain teams. The service-user credential is necessary to make API calls. In the Controller > Instances page or the API the team member can now start VM Instances with the group team1
(or 2, 3) and it will only start on the Nodes assigned to the team’s group. This is due to the Resource Permission for the Node being attached to the team group.
node
hasservice_user
hasteam1/team2/team3
hasThis configuration allows all teams to share all Anka Node capacity, but only be able to start specific VMs from specific Templates Resources assigned to their team’s Permission Group.
node
hasservice_user
hasteam1/team2/team3
hasThis configuration allows teams to have specific nodes guaranteed, then admins to increase capacity by assigning the specific team’s group to the nodes.
node
hasservice_user
hasteam1/team2/team3
hasHow to protect your Controller UI, API, and and Registry API with HTTPS/TLS.
How to protect your Controller UI, API, and Registry API with a Root Token.
How to protect your Controller UI, API, and Registry API with a Root Token and/or User API keys.
How to protect your Controller UI, API, and Registry API with Certificates.
How to set up OIDC / SSO for the Anka Build Cloud Controller UI.
How to control access and permissions using Permission Groups and Resources.