Configuring Activity Tracker in the account by using Terraform

Step 1. Install the Terraform CLI

Complete the following steps to install the Terraform CLI:

1. Create a terraform folder on your local machine, and navigate to your terraform folder.

   mkdir terraform && cd terraform
   

2. Download the Terraform version that you want. For example, you can download terraform_0.15.5_darwin_amd64.zip for a MacOS.

   The IBM Cloud Provider plug-in for Terraform currently supports Terraform version 0.12.x, 0.13.x, and 0.14.x only. Make sure to select a supported Terraform version.

3. Extract the Terraform zip file and copy the files to your terraform directory.

4. Set the environment PATH variable to your Terraform files.

   export PATH=$PATH:<terraform-directory>/terraform
   

5. Verify that the installation is successful by using a terraform command.

   ./terraform
   

Step 2. Set up the IBM Cloud Provider plug-in

After the Terraform CLI installation is complete, you must set up the IBM Cloud Provider plug-in for Terraform so that you can start working with resources and services in IBM Cloud. For a list of supported versions, see the IBM Cloud Provider plug-in releases.

The setup of the IBM Cloud Provider plug-in varies depending on the Terraform CLI version that you want to use. To run your Terraform configuration files with Terraform version 0.13.x or higher, installation of the IBM Cloud Provider plug-in for Terraform is not required. For more information, see Terraform v0.13.x and higher.

For example, to run your Terraform configuration files with Terraform version 0.13.x or higher, complete the following steps:

1. Create a versions.tf file and specify the IBM Cloud Provider plug-in version that you want to use with the version parameter.

   terraform {
       required_providers {
           ibm = {
               source = "IBM-Cloud/ibm"
               version = "<provider version>"
               }
       }
   }
   

   For example:

   terraform {
       required_version = ">= 0.15"
       required_providers {
           ibm = {
               source = "ibm-cloud/ibm"
               version = "1.48.0-beta0"
           }
       }
   }
   

2. Store the versions.tf file in your Git repository or the folder where Terraform is set up.

If you are using Terraform on IBM Cloud modules, you must add a versions.tf file to all the module folders. You can refer the Terraform provider block from the provider registry. You can use the IBM Cloud Observability - Terraform Module module to configure an instance.

Step 3. Configure the IBM Cloud Provider plug-in

After you complete the set up, you must configure the IBM Cloud Provider plug-in.

Before you can start working with Terraform on IBM Cloud, you must retrieve the credentials and parameters that are required for a Terraform resource or data source, and specify them in the provider configuration. This configuration is used by the IBM Cloud Provider plug-in to authenticate with the IBM Cloud platform and to view, create, update, or delete IBM Cloud resources and services.

The following table lists input parameters that you can set in the provider block of your Terraform on IBM Cloud configuration file:

For more information on how to use environment variables, see Using environment variables.

You can add multiple provider configurations within the same Terraform on the IBM Cloud configuration file to create your IBM Cloud resources with different provider parameters. For example, you can multiple providers so that you can use different input parameters, such as different regions, zones, infrastructure generations, or accounts to create the IBM Cloud resources in your Terraform on IBM Cloud configuration file. For more information, see Multiple Provider Instances.

Step 4. Initialize the Terraform CLI.

Next, initialize the Terraform CLI. Run the following command:

./terraform init

You should see the following message: Terraform has been successfully initialized!.

Step 5. Create a variables file

Create a variables file that is named variables.tf to include hard-coded values.

The following sample lists variables that you define:

// Data source arguments for atracker settings

variable "atracker_metadata_region_primary" {
  description = "Location where the metadata configuration is stored"
  type = string
  default = "Enter a supported location"
}

variable "atracker_metadata_region_backup" {
  description = "Location where the metadata configuration is stored"
  type = string
  default = "Enter a supported location"
}

// Data source arguments for atracker_targets
variable "target_type" {
  description = "Type of resource that can be defined as a target. Valid values are cloud_object_storage, logdna and event_streams"
  type        = string
}

variable "atracker_target_name" {
  description = "The name of the target. Must be 256 characters or less."
  type        = string
  default     = "Enter a default target name"
}

// Data source arguments for target of type cloud_object_storage
variable "cos_bucket_name" {
  description = "Name of the Cloud Object Storage bucket"
  type        = string
}

variable "cos_target_crn" {
  description = "CRN of the Cloud Object Storage bucket"
  type        = string
}

variable "cos_endpoint" {
  description = "Private endpoint of the Cloud Object Storage bucket"
  type        = string
}


// Resource arguments for atracker_route
variable "atracker_route_name" {
  description = "The name of the route. Must be 180 characters or less and cannot include any special characters other than `(space) - . _ :`."
  type        = string
  default     = "Enter a default target name"
}
variable "atracker_route_receive_global_events" {
  description = "Whether or not all global events should be forwarded to this region."
  type        = bool
  default     = false
}
variable "atracker_route_rules" {
  description = "Routing rules that will be evaluated in their order of the array."
  type        = list(object({ example=string }))
  default     = [ { example: "object" } ]
}

To see the list of valid regions, see Locations.

Step 6. Create a Terraform configuration file

Next, create a Terraform configuration file that is named main.tf. In this file, you configure Activity Tracker Event Routing by using HashiCorp Configuration Language (HCL). For more information, see the Terraform documentation.

The following code shows a sample configuration file to define the account setting configuration:

resource "ibm_atracker_settings" "atracker_settings" {
  metadata_region_primary = var.atracker_metadata_region_primary
  metadata_region_backup = var.atracker_metadata_region_backup
  default_targets = ["comma-separated-list-of-target-ids"]
  permitted_target_regions  = ["comma-separated-list-of-locations"]
  private_api_endpoint_only = false

  # Optional but recommended lifecycle flag
  lifecycle {
    create_before_destroy = true
  }
}

The following code shows sample configurations to define a target:

# Target type: cloud-object-storage
# Using service to service authorization
resource "ibm_atracker_target" "atracker_target" {
  cos_endpoint {
     endpoint = var.cos_endpoint
     target_crn = var.cos_target_crn
     bucket = var.cos_bucket_name
     service_to_service_enabled = true
  }
  name = "<Target-Name>"
  target_type = "cloud_object_storage"
  region = "us-south"
}

# Target type: cloud-object-storage
# Using a service ID Api key
resource "ibm_atracker_target" "atracker_target" {
  cos_endpoint {
     endpoint = var.cos_endpoint
     target_crn = var.cos_target_crn
     bucket = var.cos_bucket_name
     api_key = "api_key"
  }
  name = "<Target-Name>"
  target_type = "cloud_object_storage"
  region = "us-south"
}

# Target type: logdna
# Using an ingestion key
resource "ibm_atracker_target" "atracker_logdna_target" {
  logdna_endpoint {
    target_crn = "crn:v1:bluemix:public:logdna:us-south:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::"
    ingestion_key = "xxxxxxxxxxxxxx"
  }
  name = "<Target-Name>"
  target_type = "logdna"
  region = "us-south"
}

# Target type: event-streams
# Using a service ID API key
resource "ibm_atracker_target" "atracker_eventstreams_target" {
  eventstreams_endpoint {
    target_crn = "crn:v1:bluemix:public:logdna:us-south:a/11111111111111111111111111111111:22222222-2222-2222-2222-222222222222::"
    brokers = ["xxxxx.cloud.ibm.com:9093","yyyyy.cloud.ibm.com:9093"]
    topic = "my-topic"
    api_key = "api-key"
  }
  name = "<Target-Name>"
  target_type = "event_streams"
  region = "us-south"
}

The following code shows sample configurations to define a route:

## Create a route to route auditing events from Frankfurt

resource "ibm_atracker_route" "atracker_route_instance" {
  lifecycle {
    create_before_destroy = true
  }
  name = "<Route-Name>"
  rules {
    target_ids = [ibm_atracker_target.atracker_target.id]
    locations = ["eu-de"]
  }
}

## Create a route to route auditing events from 2 regions and also global events.

resource "ibm_atracker_route" "atracker_route_instance-global" {
  name = var.route_name-global

  rules {
    target_ids = [ibm_atracker_target.atracker_target-global.id]
    locations = ["global", "us-south", "eu-de"]
  }
}

## Create a route that includes multiple rules.

resource "ibm_atracker_route" "atracker_route_instance-global" {
  name = var.route_name-global

  rules {
    target_ids = [ibm_atracker_target.atracker_target-global.id]
    locations = ["eu-gb", "eu-de"]
  }
  rules {
    target_ids = [ibm_atracker_target.atracker_eventstreams_target.id]
    locations = ["us-south", "global"]
  }
}

Step 7. Provision resources

Complete the following steps:

1. Initialize the Terraform CLI.

   ./terraform init
   

2. Create a Terraform execution plan. The Terraform execution plan summarizes all the actions that need to be run to create the Activity Tracker instance, the resource Key, and IAM access policy in your account.

   ./terraform plan
   

3. Create the resources.

   ./terraform apply
   

   To delete resources, run ./terraform destroy.

What's next?

Verify that the resources are created.