Resource Template

Resource templates are the building blocks of Environment templates and include Infrastructure as Code (IaC) that defines a resource, including variables, lifecycle hooks (pre/post actions upon completion, deployment, etc.), policies, whether the resource will be dedicated per workload or shared, and more.

Did you know ?

Resource Templates can be managed through various methods:

• UI
• CLI (RCTL)
• Terraform
• GitOps
• API

Create a Resource Template

1. In a project, select Environments > Resource Templates.
2. Select New Resource Template
3. Type a name for the resource template. Optionally, type a description
4. Select Create. The resource template is created and the configuration page displays

General

Setting	Description
Version Name	Enter the version for the resource. Examples: v1, 0.1, 3
Name	Enter a name for the resource
Description	Enter a description for the resource (Optional)
Provider	Select the provider for the resource. Supported values are "Terraform (Deprecated)", "OpenTofu", and "HCP Terraform"
Provider Version	Versions <1.6.x for Terraform provider and 1.6.2, 1.7.2 or latest for OpenTofu provider
Driver	Select the driver when the provider version is not used
Labels	Add a label to the resource. Use labels to specify identifying attributes of objects that are meaningful and relevant to users, but do not directly imply semantics to the core system. This is a key-value pair. For example, the key is environment and the value is dev
Annotations	Add an annotation to the resource. Use annotations to attach arbitrary non-identifying metadata to the resource. This is a key-value pair. For example, the key is imageregistry and the value is https://hub.docker.com/

Providers

HCP Terraform

HCP Terraform is a managed service that allows teams to run Terraform together. It manages Terraform runs in a consistent and reliable environment, and includes easy access to shared state and secret data

The HCP Terraform provider option is intended for licensed HashiCorp customers. With this option, users are required to provide a custom driver to manage Terraform binaries in compliance with the BSL License. The backend type is always set to HCP Terraform, enabling centralized management of state store files etc.

Note: On selecting HCP Terraform, Custom Driver is MANDATORY

• To enable the Terraform driver to work with the Terraform Cloud organization, users need to provide a token that allows the driver to authenticate with Terraform Cloud. This token should be stored in a specific file:

File Name: .terraform.d/credentials.tfrc.json

{
    "credentials": {
        "app.terraform.io": {
            "token": "your-token-here"
          }
        }
      }

• Next step is to configure the driver to read the token from this file using an environment variable:

Environment Variable: - Key: TF_CLI_CONFIG_FILE - Value: .terraform.d/credentials.tfrc.json

Specify this file and environment variable in either of the following ways: - In the custom driver configuration used for Terraform - Using a configuration context which is then attached to the Resource Template

• Additionally, in the Container Driver, the "working directory path" value should either be set to /home/terraform or left empty (in which case, the default value will be /home/terraform).

• Add the Cloud block. You can define it's arguments in the configuration file or supply them as environment variables

OpenTofu

OpenTofu is an open-source infrastructure IaC (infrastructure as code) tool. Rafay offers first class integration for OpenTofu that allows customers to leverage OpenTofu as the IaC provisioning tool with the Environment Manager framework.

Migrating from Terraform to OpenTofu

For users looking to migrate from the deprecated Terraform Provider option to OpenTofu Provider option, the process involves the following steps.

• Create a new version of the resource template with the provider selected as OpenTofu ensuring that all other configurations remain consistent with the older template version
• Additionally, create a new version of the Environment Template that includes the updated Resource Template. This new Environment Template version can then be used to create new environments

Important

Updating an existing environment that uses Terraform provider to the new OpenTofu provider is possible by republishing the existing environment using an updated version of Environment Template (that includes Resource Template(s) with the OpenTofu provider). While this approach may work in most cases, it's important to proceed with caution as there may be risks involved. Rafay recommends creating a new environment using OpenTofu, verifying its functionality, and then deleting the older environment.

By default, a few GitHub APIs need to be accessed to download the OpenTofu binary. If the infrastructure where the agent is running does not have access to GitHub APIs, or if users prefer to download the Tofu binary from a different endpoint for operational or security reasons, this can be accommodated using the OVERRIDE_OPENTOFU_DOWNLOAD_ENDPOINT environment variable. This variable should point to any URL that hosts the Tofu binary in a zip file, and the agent will download the Tofu binary from this endpoint. Alternatively, customers can build a custom driver (based on OpenTofu) and reference that as part of the resource template configuration.

Example

OVERRIDE_OPENTOFU_DOWNLOAD_ENDPOINT=https://github.com/opentofu/opentofu/releases/download/v1.6.2/tofu_1.6.2_linux_amd64.zip

---

Repository

Setting	Description
Repository Name	Select the name for the repository
Branch	Enter the branch to use for the repository. Example: master
Directory Path	Enter the directory path for the configuration file in the repository

---

Configuration

Setting	Description
Refresh	Read the current settings from the resource and update if necessary
Lock Timeout	Lock a resource to prevent accidental modifications or deletion
State Store	State Store options differ based on the Provider selection in the General settings
Variables Management	Add var files to the resource
Plugin	Enter the plugin directory for the resource. This is optional. See Managing Plugins for more details
Volume	Configure volume settings VPC usage (mount path, storage class, and size in GB) and Backup & Restore (mount path). Users can enable the Backup & Restore during subsequent environment deployments. The volumes will be used in the deploy operation and their content will be restored. When destroying the environment, these volumes will be cleaned up

---

Hooks

A hook runs during a specified point when creating a resource from a template. Hooks can extend the functionality of creating a resource, like sending an HTTP request to a system.

Resource Hooks

Create a resource hook. See Hook Type for parameter details about each hook type.

Setting	Description
On Completion	Set a hook that is triggered when resource creation or updating is complete.
On Failure	Set a hook that is triggered when resource creation or updating fails to complete.
On Init	Set a hook that is triggered when resource creation or updating is initialized.
On Success	Set a hook that is triggered when resource creation or updating is successful.

Terraform Hooks

Create a Terraform hook. See Hook Type for parameter details about each hook type.

Deploy

Create a Terraform hook that is triggered when the resource is deployed.

Setting	Description
Init	Deploy the resource when terraform init is used.
Plan	Deploy the resource when terraform plan is used.
Apply	Deploy the resource when terraform apply is used.
Output	Deploy the resource when an output is used.

Destroy

Create a Terraform hook that is triggered when the resource is destroyed.

Setting	Description
Init	Destroy the resource when terraform init is used.
Plan	Destroy the resource when terraform plan is used.
Destroy	Destroy the resource when terraform destroy is used.

Hook Type

When adding a Resource or Terraform hook, select a hook type and set the appropriate parameters.

Approval

Setting	Description
Name	Enter a name for the hook.
Approval Type	Select the approval type. Supported values are: Internal and Email.
-- Internal
Agent Name	Select the agent to associate with this hook.
Continue on Failure	Set the hook to run even if the resource creating or updating process fails.
Timeout	Enter a value to set the timeout duration. If the timeout duration is exceeded, the resource creation or updating is terminated.

Container

Setting	Description
Name	Enter a name for the container hook
Container Configuration
-- cpuLimitMilli	Specify the CPU Limit to be used by the container
-- Image	Specify the underlying container image to be used
-- Memory Limit in MB	Specify the container memory limit to be set (in MB)
-- Working Directory Path	The working directory for commands to run in
-- Success Condition	Specify the success condition to be evaluated when a container completes execution
Arguments	Arguments to the entrypoint. The docker image's CMD is used if this is not provided
Commands	Entrypoint array. Not executed within a shell. The docker image's ENTRYPOINT is used if this is not provided
Environment Variables	Provide list of environment variables to set in the container
Agent Name	Name of the agent responsible for execution
Continue on Failure	Set the hook to continue execution even in case of failure
Timeout	Enter a value to set the timeout duration for container execution, if this exceeds container execution will be terminated

HTTP

Setting	Description
Name	Enter a name for the http hook
HTTP Configuration
-- Body	Provide message body which is the data bytes transmitted during an HTTP transaction message
-- Endpoint	Specify the http endpoint which is a targetable URL to be invoked
-- Method	Specify the http method e.g. PUT, POST, GET that corresponds to the endpoint provided
-- Success Condition	Specify the success condition to be evaluated when a http call completes execution
Headers	Specify additional context and metadata about the request
Agent Name	Name of the agent responsible for execution
Continue on Failure	Set the hook to continue execution even in case of failure
Timeout	Enter a value to set the timeout duration for http call, if this exceeds execution will be terminated

Driver Hook Type

Driver

Setting	Description
Name	Enter a name for the driver hook
Driver Configuration
-- Type	Select the driver type. Supported values are: container, http
Agent Name	Name of the agent responsible for execution
Continue on Failure	Set the hook to continue execution even in case of failure
Timeout	Specify the duration in the Timeout field for HTTP or Container. When a user specifies a timeout in both Hooks and Drivers, the timeout specified in Hooks takes precedence

---

Agents

Parameter	Description
Name	Select an agent to associate with this resource

---

Input Variables

Setting	Description
Name	The name of the variable
Description	A brief description of the variable
Value	The variable value
Value Type	The type of value
-- HCL	Hashicorp configuration language
-- JSON	JavaScript Object Notation (JSON) is a lightweight data-interchange format
-- Expressions	Expressions are valid units of code that resolve to a value
-- Text	Text value.
Override Type	Controls if a user can change a variable or not
-- Allowed	Allows the user to override the value
-- Not Allowed	Does not allow the user to override the value
-- Restricted	Allows the user to override the value by selecting a different, pre-defined value
Restricted Values	If Restricted is selected for the Override Type, enter the values that are allowed
Sensitive	Does not display the value in the UI
Required	The variable is required when using this Context

---

Contexts

Setting	Description
Context	Select a Context to associate with this resource

Upon furnishing the essential details, choose either Save as Active Version or Save as Draft Version

---

Version Management

Upon saving the configurations, users have the ability to review the list of resource templates with versions. To delve into specific version details, click on the corresponding version number.

There are three (3) distinct states for resource template versions:

• Draft
• Active
• Disabled

Users can create a draft version of resource templates and make multiple edits to it during the testing/validation phase. Once it is verified that the template is working as expected, users can transition the status from Draft to Active. However, it's important to note that no further edits can be made to the template in the active status. A new version has to be created for any edits to an Active version. Draft versions are project scoped which means that these versions are not shared with downstream projects (when the template is shared).

If a version of a template needs to be made unavailable for security related reasons or compliance, users can disable it by clicking on the Disable icon. Disabling effectively restricts further use of this version, meaning it can no longer be referenced in any new environments that are created. However, existing environments already using this version will remain unaffected.

Draft Status

In the draft status, the following rules apply:

1. Inaccessible from shared projects
2. Usable within the same project
3. Editable multiple times
4. Can be marked as active (accessible from shared projects)
5. Can be marked as disabled and restored to an active state by enabling

Active Status

For versions in the active status:

1. Cannot be reverted back to draft from any other state
2. Accessible from shared projects
3. No further changes allowed
4. Can be marked as disabled and restored to an active state by enabling

Disabled Status

Versions in the disabled status adhere to the following rules:

1. Cannot be used in the future; no impact on existing projects
2. Can be restored to an active state by enabling

Important

• Use the delete icon to remove a version if it is not currently in use. Versions cannot be deleted if they are in use
• GitOps and Terraform do not support version management; they will always synchronize with the latest active version

---