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

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:

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:

22.10.3.3.4. resource-azure-cloud

Manages Azure Instances via Resource Brokers

Learn more about:

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:

22.10.3.3.6. resource-google-cloud

Manages Google (GCE) Instances via Cloud Resource Broker

Learn more about:

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:

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:

22.10.3.3.9. resource-pnap-cloud

Manages Phoenix NAP Instances via Resource Brokers

Learn more about:

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.