IBM Cloudability onboarding Deployable Architecture (DA)

This Deployable Architecture will fully onboard a standard IBM Cloud account or an entire IBM Cloud enterprise to IBM Cloudability. The DA performs the following actions:

• Creates an encrypted Object Storage bucket to store billing reports
• Enables daily Billing Report exports to the Object Storage bucket
• Grants Cloudability access to read the billing reports from the bucket for ingestion
  • If the account is an enterprise: Grants cloudability access to read the list of child accounts in the enterprise
  • Cloudability access is controlled in a custom role so only the minimum access is given.
• Adds the IBM Cloud account/enterprise to IBM Cloudability

❗ Important: This Deployable Architecture solutions is not intended to be called by other modules because it contains a provider configuration and is therefor not compatible with the for_each, count, and depends_on arguments. For more information see Providers Within Modules

Overview

• terraform-ibm-cloudability-onboarding
• Submodules
  • billing-exports
  • cloudability-bucket-access
  • cloudability-enterprise-access
  • cloudability-onboarding
  • data-resource-instance-by-id
  • encrypted_cos_bucket
  • frontdoor-opentoken
• Contributing

Reference architectures

terraform-ibm-cloudability-onboarding

Required IAM access policies

You need the following permissions to run this module:

• IAM services
  • Cloud Object Storage service
    • Administrator platform access
    • Manager, ObjectReader service access
  • Key Protect service
    • Editor platform access
    • Manager service access
• Account management services
  • Billing service
    • Administrator platform access
  • Enterprise service (only for enterprise accounts ie. is_enterprise_account is true)
    • Administrator platform access
  • IAM Access Management service
    • Administrator platform access
  • All Account Management service (only if use_existing_resource_group is true)
    • Administrator platform access

Requirements

Name	Version
terraform	>=1.9.0
cloudability	0.0.40
ibm	1.74.0
restapi	1.20.0

Modules

Name	Source	Version
billing_exports	./modules/billing-exports	n/a
cloudability_bucket_access	./modules/cloudability-bucket-access	n/a
cloudability_enterprise_access	./modules/cloudability-enterprise-access	n/a
cloudability_onboarding	./modules/cloudability-onboarding	n/a
cos_bucket	./modules/encrypted_cos_bucket	n/a
cos_instance	./modules/data-resource-instance-by-id	n/a
frontdoor_auth	./modules/frontdoor-opentoken	n/a
resource_group	terraform-ibm-modules/resource-group/ibm	1.1.6

Resources

Name	Type
ibm_enterprises.enterprises	data source
ibm_iam_account_settings.billing_exports_account	data source
ibm_iam_auth_token.tokendata	data source

Inputs

Name	Description	Type	Default	Required
access_tags	A list of access tags to apply to the cos instance created by the module, see https://cloud.ibm.com/docs/account?topic=account-access-tags-tutorial for more details	list(string)	[]	no
activity_tracker_management_events	If set to true, all Object Storage management events will be sent to Activity Tracker.	bool	true	no
activity_tracker_read_data_events	If set to true, all Object Storage bucket read events (downloads) will be sent to Activity Tracker.	bool	true	no
activity_tracker_write_data_events	If set to true, all Object Storage bucket read events (downloads) will be sent to Activity Tracker.	bool	true	no
add_bucket_name_suffix	Add random generated suffix (4 characters long) to the newly provisioned Object Storage bucket name (Optional).	bool	true	no
archive_days	Specifies the number of days when the archive rule action takes effect. A value of null disables archiving. A value of 0 immediately archives uploaded objects to the bucket.	number	null	no
archive_type	Specifies the storage class or archive type to which you want the object to transition.	string	"Glacier"	no
bucket_cbr_rules	(Optional, list) List of CBR rules to create for the bucket	list(object({ description = string account_id = string rule_contexts = list(object({ attributes = optional(list(object({ name = string value = string }))) })) enforcement_mode = string tags = optional(list(object({ name = string value = string })), []) operations = optional(list(object({ api_types = list(object({ api_type_id = string })) }))) }))	[]	no
bucket_name	The name to give the newly provisioned Object Storage bucket.	string	"billing-reports"	no
bucket_storage_class	The storage class of the newly provisioned Object Storage bucket. Supported values are 'standard', 'vault', 'cold', 'smart' and onerate_active.	string	"standard"	no
cloudability_api_key	Cloudability API Key. Retrieve your Api Key from https://app.apptio.com/cloudability#/settings/preferences under the section Cloudability API select Enable API which will generate an api key. Setting this value to NULL will skip adding the IBM Cloud account to Cloudability and only configure IBM Cloud so that the IBM Cloud Account can be added to Cloudability manually	string	null	no
cloudability_auth_type	Select Cloudability authentication mode. Options are: * none: no connection to Cloudability * manual: manually enter in the credentials in the Cloudability UI * api_key: use Cloudability API Keys * frontdoor: Frontdoor Access Administration	string	"api_key"	no
cloudability_environment_id	An ID corresponding to your FrontDoor environment. Required if cloudability_auth_type = frontdoor	string	null	no
cloudability_host	IBM Cloudability host name as described in https://help.apptio.com/en-us/cloudability/api/v3/getting%20started%20with%20the%20cloudability.htm	string	"api.cloudability.com"	no
cloudability_iam_custom_role_name	Name of the custom role which grants access to the Cloudability service id to read the billing reports from the object storage bucket	string	"CloudabilityStorageCustomRole"	no
cloudability_iam_enterprise_custom_role_name	Name of the custom role which grants access to the Cloudability service ID to read the enterprise information. Only used if is_enterprise_account is true.	string	"CloudabilityListAccCustomRole"	no
cos_folder	Folder in the Object Storage bucket to store the account data	string	"IBMCloud-Billing-Reports"	no
cos_instance_name	The name to give the Cloud Object Storage instance that will be provisioned by this module. Only required if 'create_cos_instance' is true.	string	"billing-report-exports"	no
cos_plan	Plan to be used for creating Cloud Object Storage instance. Only used if 'create_cos_instance' is true.	string	"cos-one-rate-plan"	no
cross_region_location	Specify the cross-regional bucket location. Supported values are 'us', 'eu', and 'ap'. If you pass a value for this, ensure to set the value of var.region to null.	string	null	no
enable_billing_exports	Whether billing exports should be enabled	bool	true	no
enable_cloudability_access	Whether to grant cloudability access to read the billing reports	bool	true	no
enterprise_id	The ID of the enterprise. If __NULL__ then it is automatically retrieved if is_enterprise_account is true. Providing this value reduces the access policies that are required to run the DA.	string	null	no
existing_cos_instance_id	The ID of an existing Cloud Object Storage instance. Required if 'var.create_cos_instance' is false.	string	null	no
existing_kms_instance_crn	The CRN of an existing Key Protect or Hyper Protect Crypto Services instance. Required if 'create_key_protect_instance' is false.	string	null	no
expire_days	Specifies the number of days when the expire rule action takes effect.	number	3	no
frontdoor_public_key	The public key that is used along with the frontdoor_secret_key to authenticate requests to Cloudability. Only required if cloudability_auth_type is frontdoor. See acquiring an Access Administration API key for steps to create your credentials.	string	null	no
frontdoor_secret_key	The secret key that is used along with the frontdoor_public_key to authenticate requests to Cloudability. Only required if cloudability_auth_type is frontdoor. See acquiring an Access Administration API key for steps to create your credentials.	string	null	no
ibmcloud_api_key	The IBM Cloud API key corresponding to the cloud account that will be added to Cloudability. For enterprise accounts this should be the primary enterprise account	string	n/a	yes
instance_cbr_rules	(Optional, list) List of CBR rules to create for the instance	list(object({ description = string account_id = string rule_contexts = list(object({ attributes = optional(list(object({ name = string value = string }))) })) enforcement_mode = string tags = optional(list(object({ name = string value = string })), []) operations = optional(list(object({ api_types = list(object({ api_type_id = string })) }))) }))	[]	no
is_enterprise_account	Whether the account corresponding to the ibmcloud_api_key is an enterprise account and, if so, is the primary account within the enterprise	bool	false	no
key_name	Name of the Object Storage bucket encryption key	string	null	no
key_protect_allowed_network	The type of the allowed network to be set for the Key Protect instance. Possible values are 'private-only', or 'public-and-private'. Only used if 'create_key_protect_instance' is true.	string	"public-and-private"	no
key_protect_instance_name	Key Protect instance name	string	"cloudability-bucket-encryption"	no
key_ring_name	Name of the key ring to group keys	string	"bucket-encryption"	no
kms_endpoint_type	The type of endpoint to be used for management of key protect.	string	"public"	no
kms_rotation_enabled	If set to true, Key Protect enables a rotation policy on the Key Protect instance. Only used if 'create_key_protect_instance' is true.	bool	true	no
kms_rotation_interval_month	Specifies the number of months for the encryption key to be rotated.. Must be between 1 and 12 inclusive.	number	1	no
management_endpoint_type_for_bucket	The type of endpoint for the IBM terraform provider to use to manage the bucket. (public, private, or direct)	string	"public"	no
monitoring_crn	The CRN of an IBM Cloud Monitoring instance to send Object Storage bucket metrics to. If no value passed, metrics are sent to the instance associated to the container's location unless otherwise specified in the Metrics Router service configuration.	string	null	no
object_versioning_enabled	Enable object versioning to keep multiple versions of an object in a bucket.	bool	false	no
overwrite_existing_reports	A new version of report is created or the existing report version is overwritten with every update.	bool	true	no
policy_granularity	Whether access to the Object Storage bucket is controlled at the bucket (resource), cos instance (serviceInstance), or resource-group (resourceGroup).	string	"resource"	no
region	Region where resources are created	string	"us-south"	no
request_metrics_enabled	If set to true, all Object Storage bucket request metrics will be sent to the monitoring service.	bool	true	no
resource_group_name	The name of a new or existing resource group where resources are created	string	"cloudability-enablement"	no
resource_tags	Optional list of tags to be added to created resources	list(string)	[]	no
skip_cloudability_billing_policy	Whether policy which grants cloudability access to view the billing service. This may be true if the policy already exists because it was created by a previous run.	bool	false	no
skip_iam_authorization_policy	Set to true to skip the creation of an IAM authorization policy that permits the Object Storage instance created to read the encryption key from the KMS instance in existing_kms_instance_crn. WARNING: An authorization policy must exist before an encrypted bucket can be created	bool	false	no
skip_verification	Whether to verify that the IBM Cloud account is successfully integrated with Cloudability. This step is not strictly necessary for adding the account to Cloudability. Only applicable when cloudability_auth_type is api_key.	bool	false	no
usage_metrics_enabled	If set to true, all Object Storage bucket usage metrics will be sent to the monitoring service.	bool	true	no
use_existing_iam_custom_role	Whether the iam_custom_roles should be created or if they already exist and they should be linked with a datasource	bool	false	no
use_existing_key_ring	Whether the key_ring_name corresponds to an existing key ring or a new key ring for storing the encryption key	string	false	no
use_existing_resource_group	Whether resource_group_name input represents the name of an existing resource group or a new resource group should be created	bool	false	no

Outputs

Name	Description
bucket_account_cloudability_custom_role_display_name	Display name of the custom role that grants cloudability access to read the billing reports from the Object Storage bucket
bucket_cbr_rules	Object Storage bucket rules
bucket_crn	CRN of the Object Storage bucket where billing reports are written to
bucket_id	ID of the Object Storage bucket where billing reports are written to
bucket_name	Name of the Object Storage bucket where billing reports are written to
bucket_region	CRN of the Object Storage bucket where billing reports are written to
bucket_storage_class	Storage class of the Object Storage bucket where billing reports are written to
cos_bucket_folder	Folder in the Object Storage bucket to store the account data
cos_cbr_rule_ids	List of all rule ids
cos_instance_guid	The GUID of the Cloud Object Storage instance where the billing reports bucket is created
cos_instance_id	The ID of the Cloud Object Storage instance where the billing reports bucket is created
cos_instance_name	Name of the Cloud Object Storage instance
enterprise_account_id	ID of the IBM Cloud account or, in the case of an enterprise, the ID of the primary account in the enterprise
enterprise_cloudability_custom_role_display_name	Display name of the custom role that grants cloudability access to read the enterprise accounts
enterprise_id	id of the enterprise if is_enterprise_account is enabled
key_protect_guid	ID of the Key Protect instance which contains the encryption key for the object storage bucket
key_protect_instance_policies	Instance Polices of the Key Protect instance
key_protect_name	Name of the Key Protect instance
key_rings	IDs of new Key Rings created by the module
keys	IDs of new Keys created by the module
kms_crn	CRN of the KMS instance when an instance
kms_key_crn	The CRN of the KMS key used to encrypt the object storage bucket
resource_group_id	ID of the resource group where all resources are deployed into
s3_endpoint_direct	Direct endpoint to the Object Storage bucket where billing reports are written to
s3_endpoint_private	Private endpoint to the Object Storage bucket where billing reports are written to
s3_endpoint_public	Public endpoint to the Object Storage bucket where billing reports are written to

Contributing

You can report issues and request features for this module in GitHub issues in the module repo. See Report an issue or request a feature.

To set up your local development environment, see Local development setup in the project documentation.