22.10. cloud-wrappers - Cloud Wrappers¶
The following documentation is for Cloud Wrappers (cloud-wrappers) content package at version v4.10.0-alpha00.46+g1471cf9bbea9d50f3360a078e87e85f65fff4c7c.
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-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/instance-type¶
The type of resource assigned by the cloud provider
22.10.3.2.4. aws/region¶
Provisioning to Region for AWS
22.10.3.2.5. 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.6. 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.7. 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.8. 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.9. 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.10. azure/region¶
Region
22.10.3.2.11. 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.12. azure/size¶
Size of Azure instance
To determoine available sizes, try az vm list-sizes –location westus | jq .[].name
22.10.3.2.13. azure/subscription_id¶
Subscriber ID via az account list
22.10.3.2.14. 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.15. 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.16. 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.17. cloud/instance-id¶
The ID reference from cloud provider
22.10.3.2.18. cloud/instance-type¶
The type of resource assigned by the cloud provider
22.10.3.2.19. cloud/placement/availability-zone¶
The location of resource assigned by the cloud provider
22.10.3.2.20. 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.21. 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.22. cloud/public-hostname¶
Hostname assigned by the Cloud Provider
22.10.3.2.23. cloud/public-ipv4¶
Address assigned by the Cloud Provider
Determined by cloud-inventory
22.10.3.2.24. 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.25. 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.26. 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.27. 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.28. 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.29. google/boot-disk-image¶
Provision Google O/S Image
22.10.3.2.30. 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.31. google/instance-type¶
The type of resource assigned by the cloud provider
22.10.3.2.32. google/project-id¶
NO DEFAULT! You must supply a project name.
Provisioning to Project for Google Cloud
22.10.3.2.33. google/region¶
Provisioning to Region for Google Cloud
22.10.3.2.34. google/zone¶
Provisioning to Zone for Google Cloud
22.10.3.2.35. 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.36. linode/instance-type¶
Provision Linode allocation size
retrieve with curl https://api.linode.com/v4/linode/types | jq '.data.[].id'
22.10.3.2.37. linode/region¶
Provisioning to Region for Linode
22.10.3.2.38. linode/root-password¶
Password for Linodes If not set, should not be added to TF plan.
22.10.3.2.39. 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.40. mist/api-token¶
The ID needed to use the Mist.io API
22.10.3.2.41. oracle/availability-domain¶
Data Center Location
Must be in the oracle/region
22.10.3.2.42. oracle/compartment-id¶
Compartment for the systems being provisioned
If missing, use the oracle/tenancy
22.10.3.2.43. 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.44. 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.45. oracle/region¶
Provisioning to Region for Oracle
Consult ~/.oci/config file for location of the PEM file
22.10.3.2.46. oracle/shape¶
Sizing information for Oracle VMs
22.10.3.2.47. oracle/source-id¶
Machine Image information
Specific to a region
22.10.3.2.48. 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.49. 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.50. 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.51. 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.52. 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.53. pnap/location¶
Provision PNAP location
22.10.3.2.54. pnap/os¶
Provision Phoenix NSP O/S Image from available list
22.10.3.2.55. pnap/type¶
Provision PNAP allocation size
22.10.3.3. profiles¶
The content package provides the following profiles.
22.10.3.3.1. 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.2. resource-azure-cloud¶
Manages Azure Instances via Resource Brokers
Learn more about:
resource brokers: Resource Brokers
22.10.3.3.3. 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.4. resource-google-cloud¶
Manages Google (GCE) Instances via Cloud Resource Broker
Learn more about:
resource brokers: Resource Brokers
22.10.3.3.5. 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.6. 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.7. 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.
Designed to work with the awscli 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
