22.10. cloud-wrappers - Cloud Wrappers¶

The following documentation is for Cloud Wrappers (cloud-wrappers) content package at version v4.11.0-alpha00.69+g6fdc0a93b761e2a35c704a1d9fae2f0cd104db20.

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.

22.10.1. Requirements¶

22.10.1.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.

22.10.1.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.

22.10.1.3. Catalog Items¶

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

22.10.2. Setting Up Cloud Brokers¶

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

The cloud-profiles script in the RackN provision-content repo can be used to create the

22.10.2.1. AWS¶

aws/access-secret
aws/access-key-id

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

22.10.2.2. 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.

22.10.2.3. Linode¶

linode/token

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

22.10.2.4. 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.

22.10.3. Object Specific Documentation¶

22.10.3.1. blueprints¶

The content package provides the following blueprints.

22.10.3.1.1. broker-start-agents-via-ansible-joinup¶

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

Requires running from a Broker!

22.10.3.1.2. cloud-awscli-reconcile-instances¶

Designed to use an AWS CLI broker(s), this blueprint will call the AWS CLI describe-instances call in the aws-scan-instances task to collect information.

If unknown machines are found, they are added to Digital Rebar.

Operational Note: the range of AWS infrastructure that can be discovered is limited by the API key and region used when this is called. This will likely require multiple AWSCLI brokers to be created for full coverage.

Unlike Terraform drift detection, this process looks outside of know state for resources.

22.10.3.1.3. cloud-cluster-drift-detection¶

Designed to be used on a cron trigger, this blueprint uses passes “Plan” into the normal Terraform-Apply task via the Cluster. When running terraform plan the task will error if the known state does match the discovered state.

This allows operators to create a regular scan for clusters to ensure that they have not been changed outside of Digital Rebar Terraform management.

This is limited to the resources that were created by Terraform. To find instances that exist OUTSIDE of Terraform, use a cloud CLI task such as aws-scan-instances

22.10.3.2. params¶

The content package provides the following params.

22.10.3.2.1. aws/access-key-id¶

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.

22.10.3.2.2. aws/ami-id¶

Provision AWS O/S Image

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

22.10.3.2.3. aws/inspect¶

Collects the JSON output from AWS describe-instances call.

This is effectively a AWS API version gohai output.

22.10.3.2.4. aws/instance-type¶

The type of resource assigned by the cloud provider

22.10.3.2.5. aws/region¶

Provisioning to Region for AWS

22.10.3.2.6. aws/secret-key¶

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.

22.10.3.2.7. aws/security-groups¶

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

22.10.3.2.8. aws/vpc¶

UUID of the target VPC from AWS (e.g.: vpc-01ab234cde5d67890)

If not defined, uses the account’s AWS default VPC

22.10.3.2.9. azure/app_id¶

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”)

22.10.3.2.10. azure/image¶

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

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

22.10.3.2.11. azure/password¶

API Password

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

22.10.3.2.12. azure/region¶

Region

22.10.3.2.13. azure/security-group¶

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

22.10.3.2.14. azure/size¶

Size of Azure instance

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

22.10.3.2.15. azure/subscription_id¶

Subscriber ID via az account list

22.10.3.2.16. azure/tenant¶

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”)

22.10.3.2.17. cloud/ansible-joinup¶

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.

22.10.3.2.18. cloud/dr-install¶

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

22.10.3.2.19. cloud/instance-id¶

The ID reference from cloud provider

22.10.3.2.20. cloud/instance-type¶

The type of resource assigned by the cloud provider

22.10.3.2.21. cloud/placement/availability-zone¶

The location of resource assigned by the cloud provider

22.10.3.2.22. cloud/private-ipv4¶

Private Address assigned by the Cloud Provider

Uses terraform/map-private-ip-address to determine May also be set from cloud-inventory

22.10.3.2.23. 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!

22.10.3.2.24. cloud/public-hostname¶

Hostname assigned by the Cloud Provider

22.10.3.2.25. cloud/public-ipv4¶

Address assigned by the Cloud Provider

Determined by cloud-inventory

22.10.3.2.26. digitalocean/image¶

Provision Digital Ocean O/S Image

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

22.10.3.2.27. digitalocean/key-fingerprints¶

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.

22.10.3.2.28. digitalocean/region¶

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

22.10.3.2.29. digitalocean/size¶

Provision Digital Ocean Droplet Size

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

22.10.3.2.30. digitalocean/token¶

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.

22.10.3.2.31. google/boot-disk-image¶

Provision Google O/S Image

22.10.3.2.32. google/credential¶

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.

22.10.3.2.33. google/instance-type¶

The type of resource assigned by the cloud provider

22.10.3.2.34. google/project-id¶

NO DEFAULT! You must supply a project name.

Provisioning to Project for Google Cloud

22.10.3.2.35. google/region¶

Provisioning to Region for Google Cloud

22.10.3.2.36. google/zone¶

Provisioning to Zone for Google Cloud

22.10.3.2.37. linode/instance-image¶

Provision Linode O/S Image

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

22.10.3.2.38. linode/instance-type¶

Provision Linode allocation size

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

22.10.3.2.39. linode/region¶

Provisioning to Region for Linode

22.10.3.2.40. linode/root-password¶

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

22.10.3.2.41. linode/token¶

The token required by cloud provider to act aginst the API

Make sure the Token has the following authority:

create Linodes
create Stackscripts
create Domains

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

22.10.3.2.42. mist/api-token¶

The ID needed to use the Mist.io API

22.10.3.2.43. oracle/availability-domain¶

Data Center Location

Must be in the oracle/region

22.10.3.2.44. oracle/compartment-id¶

Compartment for the systems being provisioned

If missing, use the oracle/tenancy

22.10.3.2.45. oracle/fingerprint¶

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.

22.10.3.2.46. oracle/private-key¶

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.

22.10.3.2.47. oracle/region¶

Provisioning to Region for Oracle

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

22.10.3.2.48. oracle/shape¶

Sizing information for Oracle VMs

22.10.3.2.49. oracle/source-id¶

Machine Image information

Specific to a region

22.10.3.2.50. oracle/subnet-id¶

Subnet to use for Oracle network access

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

22.10.3.2.51. oracle/tenancy-ocid¶

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.

22.10.3.2.52. oracle/user-ocid¶

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.

22.10.3.2.53. pnap/client-id¶

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.

22.10.3.2.54. pnap/client-secret¶

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.

22.10.3.2.55. pnap/location¶

Provision PNAP location

22.10.3.2.56. pnap/os¶

Provision Phoenix NSP O/S Image from available list

22.10.3.2.57. pnap/type¶

Provision PNAP allocation size

22.10.3.3. profiles¶

The content package provides the following profiles.

22.10.3.3.1. bootstrap-cloud-wrappers¶

Bootstrap Digital Rebar server for advanced operation

Cloud Wrappers * Downloads context containers

This is designed to be extended or replaced with a site specific bootstrap that uses the base tasks but performs additional bootstrapping.

22.10.3.3.2. resource-aws-cli¶

Manages AWS CLI via Resource Brokers

Used to create a Resource Broker to run the AWS CLI.

Learn more about:

resource brokers: Resource Brokers

22.10.3.3.3. resource-aws-cloud¶

Manages AWS Instances via Resource Brokers

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

Learn more about:

resource brokers: Resource Brokers

22.10.3.3.4. resource-azure-cloud¶

Manages Azure Instances via Resource Brokers

Learn more about:

resource brokers: Resource Brokers

22.10.3.3.5. resource-digitalocean-cloud¶

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:

resource brokers: Resource Brokers

22.10.3.3.6. resource-google-cloud¶

Manages Google (GCE) Instances via Cloud Resource Broker

Learn more about:

resource brokers: Resource Brokers

22.10.3.3.7. resource-linode-cloud¶

Manages Linode Instances via Resource Brokers

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

Learn more about:

resource brokers: Resource Brokers

22.10.3.3.8. resource-oracle-cloud¶

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:

resource brokers: Resource Brokers

22.10.3.3.9. resource-pnap-cloud¶

Manages Phoenix NAP Instances via Resource Brokers

Learn more about:

resource brokers: Resource Brokers

22.10.3.4. tasks¶

The content package provides the following tasks.

22.10.3.4.1. aws-scan-instances¶

Uses AWS CLI content to scan AWS inventory and find instances that do not exist in Digital Rebar. Then create machines with information for the unregistered machines.

Operational Note: the range of AWS infrastructure that can be discovered is limited by the API key and region used when this is called.

When detecting drift (machines in AWS that are not known to Digital Rebar), scan will raise an aws.drift.[cluster name] event with the created machine ID and AWS instance ID.

Designed to work with the awscli-runner context

22.10.3.4.2. cloud-validate¶

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!

22.10.3.4.3. inject-ansible-joinup¶

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

22.10.3.4.4. mist-io-sync¶

Make sure instance is registered with Mist.io

22.10.3.5. triggers¶

The content package provides the following triggers.

22.10.3.5.1. cloud-drift-alert¶

Catches *.drift.[cluster name] events emitted from terraform-apply and aws-scan-instances. Then uses that information to raise an Alert.

This is designe to be a generic drift event catch.