This guide requires an Anka Enterprise (or higher) license.
For this tutorial you will need:
The guide will show you how to generate self-signed versions of these. If you already have certificates, you can skip the generation steps/commands.
If you're using a signed certificate for the controller dashboard, but self-signed certificates for your nodes and CI tools, you'll need to specify the
--cacert
forankacluster join
andanka registry add
commands and point it to the signed CA certificate. You'll usually seeSSLError: ("bad handshake: Error([('SSL routines', 'tls_process_server_certificate', 'certificate verify failed')],)",)
if the wrong CA is being used.
If you don’t have a, you can create it with openssl and add it to your keychain:
cd ~
openssl req -new -nodes -x509 -days 365 -keyout anka-ca-key.pem -out anka-ca-crt.pem -subj "/C=$COUNTRY/ST=$STATE/L=$LOCATION/O=$ORGANIZATION/OU=$ORG_UNIT/CN=$CA_CN"
# Add the Root CA to the System keychain so the Root CA is trusted
sudo security add-trusted-cert -d -k /Library/Keychains/System.keychain anka-ca-crt.pem
The Controller certificate is not part of the authentication process and doesn't need to be derived from the CA you just generated. This means that you can use certificates supplied by your organization or a 3rd party.
For this guide, we're running the Controller & Registry locally, so we use 127.0.0.1. Update this depending on where you have things hosted.
If you do not have TLS certificates for your Controller & Registry, you can create them now:
export CONTROLLER_ADDRESS="127.0.0.1"
export REGISTRY_ADDRESS=$CONTROLLER_ADDRESS
openssl genrsa -out anka-controller-key.pem 4096
openssl req -new -nodes -sha256 -key anka-controller-key.pem -out anka-controller-csr.pem -subj "/C=$COUNTRY/ST=$STATE/L=$LOCATION/O=$ORGANIZATION/OU=$ORG_UNIT/CN=$CONTROLLER_CN" -reqexts SAN -extensions SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nextendedKeyUsage = serverAuth\nsubjectAltName=IP:$CONTROLLER_ADDRESS"))
openssl x509 -req -days 365 -sha256 -in anka-controller-csr.pem -CA anka-ca-crt.pem -CAkey anka-ca-key.pem -CAcreateserial -out anka-controller-crt.pem -extfile <(echo subjectAltName = IP:$CONTROLLER_ADDRESS)
You can use the same certificate for both.
Ensure that the certificate has Signature Algorithm: sha256WithRSAEncryption using openssl x509 -text -noout -in ~/anka-controller-crt.pem | grep Signature
(https://support.apple.com/en-us/HT210176)
Edit /usr/local/bin/anka-controllerd
in the following manner:
LISTEN_ADDRESS=":80"
to LISTEN_ADDRESS=":443"
SSL will work on any port you want.
Append the following parameters on the end of the $CONTROLLER_BIN line:
--use-https --server-cert /Users/$USER_WHERE_CERTS_ARE/anka-controller-crt.pem --server-key /Users/$USER_WHERE_CERTS_ARE/anka-controller-key.pem --anka-registry "https://$REGISTRY_ADDRESS:8089" --registry-listen-address "$REGISTRY_ADDRESS:8089"
The Controller & Registry runs as root; This is why you need to specify the absolute path to the location where you generated the certs.
Within the docker-compose.yml
:
80:80
to 443:80
. You can keep the anka-registry ports the same.https://
.****EDIT_ME****
to the location you created your certificates in for both anka-controller and anka-registry:. . .
anka-controller:
build:
context: .
dockerfile: anka-controller.docker
ports:
- "80:80"
# To change the port, change the above line: - "CUSTOM_PORT:80"
###### EDIT HERE FOR TLS ########
# volumes:
# Path to ssl certificates directory
# - ****EDIT_ME****:/mnt/cert
. . .
Now let’s configure the Controller & Registry containers/services to use those certificates. Search for the environment variables USE_HTTPS, SERVER_CERT and SERVER_KEY in docker-compose.yml
, uncomment the lines, and then modify the ****EDIT_ME****
with the name of your certificate for both anka-controller and anka-registry:
. . .
anka-controller:
build:
context: .
dockerfile: anka-controller.docker
ports:
- "443:80"
# To change the port, change the above line: - "CUSTOM_PORT:80"
###### EDIT HERE FOR TLS ########
volumes:
# Path to ssl certificates directory
- /home/ubuntu:/mnt/cert
depends_on:
- etcd
# - beanstalk
- anka-registry
restart: always
environment:
# Address of anka registry. this address will be passed to your build Nodes
ANKA_REGISTRY_ADDR: https://<REGISTRY_ADDRESS>:8089
. . .
###### EDIT HERE FOR TLS ########
# Use https, if enabled Controller will use tls for http communication
# USE_HTTPS: --use-https
# Server certificate pem
# SERVER_CERT: --server-cert /mnt/cert/****EDIT_ME****
# Server private key pem
# SERVER_KEY: --server-key /mnt/cert/****EDIT_ME****
. . .
Make sure to perform the same changes for the anka-registry container.
Start or restart your Controller and test the new TLS configuration using https://
. You can also try using curl -v https://$HOST/api/v1/status
.
If that doesn’t work, try to repeat the above steps and validate that the file names and paths are correct. If you are still having trouble, debug the system as explained in the Debugging Controller section.
The Controller's authentication module uses the Root CA (anka-ca-crt.pem) to authenticate the Node certificates. When the Node sends the requests to the Controller, it will present it's certificates. Those certificates will then be validated against the configured CA.
You can use the following openssl commands to create Node certificates using the Root CA:
openssl genrsa -out node-$NODE_NAME-key.pem 4096
openssl req -new -sha256 -key node-$NODE_NAME-key.pem -out node-$NODE_NAME-csr.pem -subj "/C=$COUNTRY/ST=$STATE/L=$LOCATION/O=$ORGANIZATION/OU=$ORG_UNIT/CN=$NODE_NAME"
openssl x509 -req -days 365 -sha256 -in node-$NODE_NAME-csr.pem -CA anka-ca-crt.pem -CAkey anka-ca-key.pem -CAcreateserial -out node-$NODE_NAME-crt.pem
The CA_CERT is the authority that is used to validate the node certificates you'll pass in later.
Edit the /usr/local/bin/anka-controllerd
and add the following onto the end of the $CONTROLLER_BIN line:
--enable-auth --ca-cert /Users/$USER_WHERE_CERTS_ARE/anka-ca-crt.pem
Within the docker-compose.yml
, search for the environment variables ENABLE_AUTH and CA_CERT. Edit both anka-controller and anka-registry so they look like the configuration below (assuming that a certificate folder is already mounted at /mnt/cert).
. . .
anka-controller:
build:
context: .
dockerfile: anka-controller.docker
ports:
- "443:80"
# To change the port, change the above line: - "CUSTOM_PORT:80"
volumes:
# Path to ssl certificates directory
- /home/ubuntu:/mnt/cert
depends_on:
- etcd
# - beanstalk
restart: always
environment:
. . .
USE_HTTPS: --use-https
# Server certificate pem
SERVER_CERT: --server-cert /mnt/cert/anka-controller-crt.pem
# Server private key pem
SERVER_KEY: --server-key /mnt/cert/anka-controller-key.pem
ENABLE_AUTH: --enable-auth
CA_CERT: --ca-cert /mnt/cert/anka-ca-crt.pem
. . .
Make sure to perform the same changes for the anka-registry container.
Until you have a Node joined to the Controller, it won't see your Enterprise license and won't enable authentication.
If you're connecting the Anka CLI with the HTTPS Registy, you can use the Node certificates:
anka registry --cert /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-crt.pem --key /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-key.pem --cacert /Users/$USER_WHERE_CERTS_ARE/anka-ca-crt.pem add $REGISTRY_NAME https://$REGISTRY_ADDRESS:8089
If you previously joined your Nodes to the Controller, you'll want to
sudo ankacluster disjoin
on each before proceeding (if it hangs, useps aux | grep anka_agent | awk '{print $2}' | xargs kill -9
and try disjoin again).
Copy both the Node certificates (node-$NODE_NAME-crt.pem, node-$NODE_NAME-key.pem) and the anka-ca-crt.pem to the Node.
Then, use the ankacluster
command to connect it to the Controller in the following manner:
sudo ankacluster join https://$CONTROLLER_ADDRESS --cert /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-crt.pem --cert-key /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-key.pem --cacert /Users/$USER_WHERE_CERTS_ARE/anka-ca-crt.pem
You should see output similar to the following:
Testing connection to Controller...: OK
Testing connection to registry….: OK
Ok
Cluster join success
Restart your Controller & Registry and then test the status endpoint with curl:
curl -v https://$HOST/api/v1/status
The response you should get is a 401 Authentication Required similar to below:
> GET /api/v1/status HTTP/2
> Host: localhost:80
> User-Agent: curl/7.58.0
> Accept: */*
>
* Connection state changed (MAX_CONCURRENT_STREAMS updated)!
< HTTP/2 401
< content-type: application/json
< content-length: 54
< date: Thu, 28 Nov 2019 16:58:23 GMT
<
{"status":"FAIL","message":"Authentication Required"}
If this is the response you get, it means the authentication module is working.
Let’s try to get a response using the Node certificate we created. Execute the same command, but now pass Node certificate and key:
curl -v https://$CONTROLLER_ADDRESS/api/v1/status --cert /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-crt.pem --key /Users/$USER_WHERE_CERTS_ARE/node-$NODE_NAME-key.pem
If everthing is configured correctly, you should see something like this (I used 127.0.0.1 to setup this example):
* Trying 127.0.0.1...
. . .
> GET /api/v1/status HTTP/2
> Host: 127.0.0.1:80
> User-Agent: curl/7.64.1
> Accept: */*
>
* Connection state changed (MAX_CONCURRENT_STREAMS == 250)!
< HTTP/2 200
< cache-control: no-store
< content-type: application/json
< content-length: 184
< date: Sun, 12 Apr 2020 04:26:13 GMT
<
{"status":"OK","message":"","body":{"status":"Running","version":"1.7.0-4e6617d3","registry_address":"https://127.0.0.1:8089","registry_status":"Running","license":"enterprise plus"}}
* Connection #0 to host 127.0.0.1 left intact
* Closing connection 0
This feature requires Enterprise Plus
Permission groups are configurable from your Controller's https://<controller address>/admin/ui
page.
The permission groups here differ from the groups you assign to nodes
When creating your certificates, you'll want to specify CSR values using openssl's -subj
option. For example, if we're going to generate a certificate so our Jenkins instance can access the Controller & Registry, you'll want to use something like this:
-subj "/C=$COUNTRY/ST=$STATE/L=$LOCATION/O=MyOrgName/OU=$ORG_UNIT/CN=Jenkins"
The two required values to set are
O=
andCN=
Spaces are not currently supported in
O=
Within the Controller, we use O=
as the permission group and CN=
as the username.
Once you've setup your certificate, you can then create a New Group in the /admin/ui panel. The Group Name will be MyOrgName, like we used in the -subj
above.
The Available Permissions will display all of the permissions we can assign to the group. For Jenkins, we'll want the following:
get_groups
get_registry_disk_info
head_push_vms
list_images
list_nodes
list_vms
pull_vm
push_vm
registry_list
save_image
start_vm
terminate_vm
update_vm
upload_file
view_logs
These permissions will allow the Anka Jenkins Plugin to communicate with the Controller & Registry.
Was this page helpful?
Glad to hear it! Please tell us how we can improve.
Sorry to hear that. Please tell us how we can improve.