Cloud Auto-join

Cloud Auto-joining

As of Dkron 2.0.0, retry-join accepts a unified interface using the go-discover library for doing automatic cluster joining using cloud metadata. To use retry-join with a supported cloud provider, specify the configuration on the command line or configuration file as a key=value key=value ... string.

If the values contain spaces, equals, backslashes or double quotes then they need to be double quoted and the usual escaping rules apply.

$ dkron agent --retry-join 'provider=my-cloud config=val config2="some other val" ...'

or via a configuration file:

retry-join": ["provider=my-cloud config=val config2=\"some other val\" ..."]

The cloud provider-specific configurations are detailed below. This can be combined with static IP or DNS addresses or even multiple configurations for different providers.

In order to use discovery behind a proxy, you will need to set HTTP_PROXY, HTTPS_PROXY and NO_PROXY environment variables per Golang net/http library.

The following sections give the options specific to each supported cloud provider.

Amazon EC2

This returns the first private IP address of all servers in the given region which have the given tag_key and tag_value.

$ dkron agent --retry-join "provider=aws tag_key=... tag_value=..."
retry-join: ["provider=aws tag_key=... tag_value=..."]

Authentication & Precedence

The only required IAM permission is ec2:DescribeInstances, and it is recommended that you make a dedicated key used only for auto-joining. If the region is omitted it will be discovered through the local instance’s EC2 metadata endpoint.

Microsoft Azure

This returns the first private IP address of all servers in the given region which have the given tag_key and tag_value in the tenant and subscription, or in the given resource_group of a vm_scale_set for Virtual Machine Scale Sets.

$ dkron agent --retry-join "provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."
retry-join: ["provider=azure tag_name=... tag_value=... tenant_id=... client_id=... subscription_id=... secret_access_key=..."]

Variables can also be provided by environmental variables:

Use these configuration parameters when using tags:

Use these configuration parameters (instead of tag_name and tag_value) when using Virtual Machine Scale Sets (Dkron 1.0.3 and later):

When using tags the only permission needed is Microsoft.Network/networkInterfaces.

When using Virtual Machine Scale Sets the only role action needed is Microsoft.Compute/virtualMachineScaleSets/*/read.

Google Compute Engine

This returns the first private IP address of all servers in the given project which have the given tag_value.

$ dkron agent --retry-join "provider=gce project_name=... tag_value=..."
retry_join: ["provider=gce project_name=... tag_value=..."]

Authentication & Precedence

Discovery requires a GCE Service Account. Credentials are searched using the following paths, in order of precedence.

IBM SoftLayer

This returns the first private IP address of all servers for the given datacenter with the given tag_value.

$ dkron agent --retry-join "provider=softlayer datacenter=... tag_value=... username=... api_key=..."
retry-join: ["provider=softlayer datacenter=... tag_value=... username=... api_key=..."]

Aliyun (Alibaba Cloud)

This returns the first private IP address of all servers for the given region with the given tag_key and tag_value.

$ dkron agent --retry-join "provider=aliyun region=... tag_key=dkron tag_value=... access_key_id=... access_key_secret=..."
retry-join: ["provider=aliyun region=... tag_key=dkron tag_value=... access_key_id=... access_key_secret=..."]

The required RAM permission is ecs:DescribeInstances. It is recommended you make a dedicated key used only for auto-joining.

Digital Ocean

This returns the first private IP address of all servers for the given region with the given tag_name.

$ dkron agent --retry-join "provider=digitalocean region=... tag_name=... api_token=..."
retry-join: ["provider=digitalocean region=... tag_name=... api_token=..."]

Openstack

This returns the first private IP address of all servers for the given region with the given tag_key and tag_value.

$ dkron agent --retry-join "provider=os tag_key=dkron tag_value=server username=... password=... auth_url=..."
retry-join: ["provider=os tag_key=dkron tag_value=server username=... password=... auth_url=..."]

The configuration can also be provided by environment variables.

Scaleway

This returns the first private IP address of all servers for the given region with the given tag_name.

$ dkron agent --retry-join "provider=scaleway organization=my-org tag_name=dkron-server token=... region=..."
retry-join: ["provider=scaleway organization=my-org tag_name=dkron-server token=... region=..."]

Joyent Triton

This returns the first PrimaryIP addresses for all servers with the given tag_key and tag_value.

$ dkron agent --retry-join "provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=dkron-role tag_value=server"
retry-join: ["provider=triton account=testaccount url=https://us-sw-1.api.joyentcloud.com key_id=... tag_key=dkron-role tag_value=server"]

vSphere

This returns the first private IP address of all servers for the given region with the given tag_name and category_name.

$ dkron agent --retry-join "provider=vsphere category_name=dkron-role tag_name=dkron-server host=... user=... password=... insecure_ssl=[true|false]"
retry-join: ["provider=vsphere category_name=dkron-role tag_name=dkron-server host=... user=... password=... insecure_ssl=[true|false]"]

Packet

This returns the first private IP address (or the IP address of address type) of all servers with the given project and auth_token.

$ dkron agent --retry-join "provider=packet auth_token=token project=uuid url=... address_type=..."
retry-join: ["provider=packet auth_token=token project=uuid url=... address_type=..."]

Kubernetes (k8s)

The Kubernetes provider finds the IP addresses of pods with the matching label or field selector. This is useful for non-Kubernetes agents that are joining a server cluster running within Kubernetes.

The pod IP is used by default, which requires that the agent connecting can network to the pod IP. The host_network boolean can be set to true to use the host IP instead, but this requires the agent ports (Gossip, RPC, etc.) to be exported to the host as well.

By default, no port is specified. This causes Dkron to use the default gossip port (default behavior with all join requests). The pod may specify the dkron.hashicorp.com/auto-join-port annotation to set the port. The value may be an integer or a named port.

$ dkron agent --retry-join "provider=k8s label_selector=\"app=dkron,component=server\""
retry-join: ["provider=k8s label_selector=..."]