23.10. cloud-wrappers - Cloud Wrappers

The following documentation is for Cloud Wrappers (cloud-wrappers) content package at version v4.9.0-alpha00.67+g2af61053ec23a91be2e566ecf386ec23b2ae1119.

This library contains items that help run Digital Rebar manage machines on public clouds. It uses Terraform tasks to create/delete machines and Ansible tasks join the machine to install the Digital Rebar runner. Once the runners starts, it will collect cloud specific data if a Metadata API is available.

TL;DR: cloud-provision uses the v4.8 Resource Brokers to create and attach machines to Terraform accessible platform.

23.10.1. Inbound Access

The Digital Rebar Server must be at a location that is accessible to the machines being provisioned. This is required because the machines must be able to download the join-up script from the server using port 8090.

23.10.2. Outbound Access

Is NOT required unless you are using a cloud provider that requires SSH into the newly created machines.

As of v4.8, none of the major cloud providers (AWS, Azure, Google, Linode, Digital Ocean) required SSH to join-up.

23.10.3. Catalog Items

The Cloud Wrapper requires Contexts because it uses Runner and Terraform. If SSH is required then the Ansible Context is used.

23.10.3.1. Setting Up Cloud Brokers

When you create a Cloud Broker, you must set Security credentials for each cloud.

The `cloud-profiles script<https://gitlab.com/rackn/provision-content/-/blob/v4/tools/cloud-profiles.sh>`_ in the RackN provision-content repo can be used to create the

23.10.4. AWS

  • aws/access-secret

  • aws/access-key-id

Additional values, e.g. region, image and instance type, have safe defaults but should be reviewed.

23.10.5. Google

  • google/credential - this is a copy of contents from the JSON file Google provides

Additional values, e.g. region, image and instance type, have safe defaults but should be reviewed.

23.10.6. Linode

  • linode/token

Additional values, e.g. region, image and instance type, have safe defaults but should be reviewed.

23.10.7. Optional Values

When possble, the machine on the cloud provider is given the name of the machine in Digital Rebar.

The reference terraform plan will create tags on the cloud provider based on the assigned profiles. It also creates one called “digitalrebar.” This can be handy to find or manage the machines on the cloud provider.

23.10.7.1. Object Specific Documentation

23.10.8. params

The content package provides the following params.

The ID needed to use the AWS secret

If you have the aws cli installed, you can retrieve this key using cat ~/.aws/credentials and then using the aws_access_key_id value.

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Provision AWS O/S Image

Default is Amazon Linux 11/11/21 for us-west-2

The type of resource assigned by the cloud provider

Provisioning to Region for AWS

The token required by cloud provider to act aginst the API

If you have the aws cli installed, you can retrieve this key using cat ~/.aws/credentials and then using the aws_secret_access_key value.

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Comma seperated list of security groups to be applied to during Terraform plan construction

Only the list values are used, the enclosing [] are added by the cloud-provision-aws-instance.tf.tmpl template.

Default of aws_security_group.digitalrebar_basic.name is created by the default aws template cloud-provision-aws-security-group.tf.tmpl

App ID from

::

azure_subscription_id=$(az account list | jq -r ‘.[0].id’) az account set –subscription=”$azure_subscription_id” azure_resource=$(az ad sp create-for-rbac –role=”Contributor” –scopes=”/subscriptions/$azure_subscription_id”)

Image Information for Azure including * publisher * offer * sku * version

To find images using the Azure CLI: az vm image list -f Ubuntu –all

API Password

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Region

Name of security group id to be applied to during Terraform plan construction

The value is used exactly as provided in the azurerm_network_interface_security_group_association resource block so should include the .id or other key information.

Default of azurerm_network_security_group.security_group.id is created by the default azure template cloud-provision-azure-app.tf.tmpl

Size of Azure instance

To determoine available sizes, try az vm list-sizes –location westus | jq .[].name

Subscriber ID via az account list

API Tenant from

::

azure_subscription_id=$(az account list | jq -r ‘.[0].id’) az account set –subscription=”$azure_subscription_id” azure_resource=$(az ad sp create-for-rbac –role=”Contributor” –scopes=”/subscriptions/$azure_subscription_id”)

Indicate that cloud-provision process should inject ansible-join-up into the created task lists.

This is used when the Terraform Provider cannot use a cloud-init type join.

See the resource-google-cloud for an example.

Internal operations flag used to identify if cloud provision is used This is set inside on the user’s behalf in the cloud-site-* stages

The ID reference from cloud provider

The type of resource assigned by the cloud provider

The location of resource assigned by the cloud provider

The cloud provider detected by join-up script

Custom types are supported by adding Terraform plan template ‘cloud-provision-[provider].tf.tmpl’

Implemented types:

  • aws (Amazon Web Services)

  • google (Google Compute Engine)

  • linode

  • azure (Microsoft Cloud)

  • digitalocean

  • pnap (Phoenix NAP)

  • oracle

Expand this list as new types are added!

Hostname assigned by the Cloud Provider

Address assigned by the Cloud Provider

Provision Digital Ocean O/S Image

Retrieve list of images: curl -X GET -H “Content-Type: application/json” -H “Authorization: Bearer $DO_TOKEN” “https://api.digitalocean.com/v2/images” | jq .images[].slug

The fingerprint(s) of the SSH key(s) registered with Digital Ocean that should be installed in the Droplet

WARNING: these are NOT the SSH keys created by the cluster automation. They must be uploaded into Digital Ocean and will be installed based on the stored figerprints.

This is an array so multiple fingerprints can be added.

Provisioning to Region for Digital Ocean

List of regions: curl -X GET -H “Content-Type: application/json” -H “Authorization: Bearer $DO_KEY” “https://api.digitalocean.com/v2/regions” | jq .regions[].slug

Provision Digital Ocean Droplet Size

Retrieve list of sizes: curl -X GET -H “curl -X GET -H “Content-Type: application/json” -H “Authorization: Bearer $DO_TOKEN” “https://api.digitalocean.com/v2/sizes” | jq .sizes[].slug

The token required by cloud provider to act aginst the API

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Provision Google O/S Image

The token required by cloud provider to act aginst the API

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The type of resource assigned by the cloud provider

NO DEFAULT! You must supply a project name.

Provisioning to Project for Google Cloud

Provisioning to Region for Google Cloud

Provisioning to Zone for Google Cloud

Provision Linode O/S Image

To generate, use curl https://api.linode.com/v4/images | jq '.data.[].id'

Provision Linode allocation size

retrieve with curl https://api.linode.com/v4/linode/types | jq '.data.[].id'

Provisioning to Region for Linode

Password for Linodes If not set, should not be added to TF plan.

The token required by cloud provider to act aginst the API

Make sure the Token has the following authority:

  1. create Linodes

  2. create Stackscripts

  3. create Domains

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The ID needed to use the Mist.io API

Data Center Location

Must be in the oracle/region

Compartment for the systems being provisioned

If missing, use the oracle/tenancy

The fingerprint required by cloud provider to act aginst the API

Consult ~/.oci/config file for this value

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The private key required by cloud provider to act aginst the API.

The private key is required for Terraform to correctly validate operations from the Digital Rebar server. The private key is registered by the Oracle cloud.

Consult ~/.oci/config file for location of the PEM file

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Provisioning to Region for Oracle

Consult ~/.oci/config file for location of the PEM file

Sizing information for Oracle VMs

Machine Image information

Specific to a region

Subnet to use for Oracle network access

Must be supplied by operator. In the future could be created by Terraform

The tenancy ocid required by cloud provider to act aginst the API

Consult ~/.oci/config file for location of the PEM file

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The user ocid required by cloud provider to act aginst the API

Consult ~/.oci/config file for location of the PEM file

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The ID required by cloud provider to act aginst the API

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

The token required by cloud provider to act aginst the API

You can also use the cloud broker install script to create resource brokers from local configuraiton information.

Provision PNAP location

Provision Phoenix NSP O/S Image from available list

Provision PNAP allocation size

23.10.9. profiles

The content package provides the following profiles.

Manages AWS Instances via Resource Brokers

Sets the rsa/key-user to the AWS default of ec2-user

Learn more about:

Manages Azure Instances via Resource Brokers

Learn more about:

Manages Digital Ocean Instances via Resource Brokers

NOTICE: terraform-apply retry is a workaround for unreliability in the Digital Ocean provider. Generally, the DO provider will create resources well but may have trouble doing updates on existing resources as of Dec 2021 with the error: 401 … Unable to authenticate you. There are several defensive changes to the plans to work around these issues.

Learn more about:

Manages Google (GCE) Instances via Cloud Resource Broker

Learn more about:

Manages Linode Instances via Resource Brokers

WORKAROUND: task-retry value included to address Terraform Provider issue related to deleting all resources

Learn more about:

Manages Oracle Instances via Resource Brokers

This broker relies on the private/public key pair for authorization in the Oracle cloud. You will need to create a key pair and upload the private key under oracle/private-key.

Note: SSH user is opc!

Learn more about:

Manages Phoenix NAP Instances via Resource Brokers

Learn more about:

23.10.10. tasks

The content package provides the following tasks.

Used as a validate that the right params have been set for cloud scenarios and provide operator friendly feedback in the Machine.Description

Maintainer Notes: Remember to synchronize with the cloud/provider enum!

For cloud providers that do not support injecting a start-up script, add the Ansible Join Up and start the Ansible context.

Will skip if cloud/ansible-joinup is false. Requires that rsa-public-key is installed for ssh on the provisioned machine

Make sure instance is registered with Mist.io

23.10.11. work_order_templates

The content package provides the following work_order_templates.

Will perform the task that is used by non-cloud-init brokers.

Requires running from a Broker!