Skip to main content

almaforge_role Resource

Manage an AlmaForge Role resource.

Before you start​

Use the Terraform setup guide to install the provider and sign in. Your identity needs permission to manage this resource. Keep one owner for each resource name, following the ownership rules.

A role defines permissions. Creating it does not assign it to anyone. Assign it through SSO role mapping or make it available through access requests.

Read the RBAC guide for allow/deny rules, target labels, and administrative permissions. The example permits the ubuntu login on SSH servers labeled env=dev. The label on the role itself only helps organize roles. It does not select servers.

Example Usage​

Download main.tf into its own directory. Replace example values with your cluster and integration settings. Use the plan and apply workflow after preparing the prerequisites above.

HCL
# Manage an API-owned role after authenticating with alma login.
terraform {
  required_providers {
    almaforge = {
      source = "get.almaforge.com/almaforge/almaforge"
    }
  }
}

provider "almaforge" {}

resource "almaforge_role" "developers" {
  metadata = {
    name = "developers"
    labels = {
      managed_by = "terraform"
    }
  }
  spec = {
    allow = {
      server_logins = ["ubuntu"]
      server_labels = {
        env = ["dev"]
      }
    }
  }
}

See the configuration reference for the resource manifest and field context.

Changes and deletion​

Configuration is authoritative. Removing an optional attribute resets its API default or clears it when no default exists. Changing metadata.name replaces the resource. Review the plan before applying. See lifecycle behavior.

Removing a grant revokes it on apply. Before deleting a role, remove its assignments and references. Keep a separate administrator available and review break-glass recovery.

To read an existing object without managing it, use the named data source.

Schema​

Required​

Optional​

Nested Schema for metadata​

Required:

  • name (String) Resource name. Changing this name replaces the resource.

Optional:

  • labels (Map of String) Labels attached to the resource.

Read-Only:

  • resource_version (String) Server revision used to detect concurrent changes.

Nested Schema for spec​

Optional:

  • allow (Attributes) Allow is the set of conditions evaluated to grant access. (see below for nested schema)
  • deny (Attributes) Deny is the set of conditions evaluated to deny access. Deny takes priority over allow. (see below for nested schema)
  • options (Attributes) Options is for OpenSSH options like agent forwarding. (see below for nested schema)

Nested Schema for spec.allow​

Optional:

  • app_labels (Map of List of String) AppLabels is a map of labels used as part of the RBAC system.
  • app_labels_expression (String) AppLabelsExpression is a predicate expression used to allow/deny access to AppTargets.
  • database_labels (Map of List of String) DatabaseLabels are used in RBAC system to allow/deny access to databases.
  • database_labels_expression (String) DatabaseLabelsExpression is a predicate expression used to allow/deny access to DatabaseTargets.
  • database_names (List of String) DatabaseNames is a list of database names this role is allowed to connect to.
  • database_roles (List of String) DatabaseRoles is a list of database roles for automatic user creation.
  • database_service_labels (Map of List of String) DatabaseServiceLabels are used in RBAC system to allow/deny access to Database Services.
  • database_service_labels_expression (String) DatabaseServiceLabelsExpression is a predicate expression used to allow/deny access to Database Services.
  • database_users (List of String) DatabaseUsers is a list of database users this role is allowed to connect as.
  • host_groups (List of String) HostGroups is a list of groups for created users to be added to.
  • host_sudoers (List of String) HostSudoers is a list of entries to include in a user's sudoer file.
  • impersonate (Attributes) Impersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means. (see below for nested schema)
  • kubernetes_groups (List of String) KubernetesGroups is a list of kubernetes groups.
  • kubernetes_labels (Map of List of String) KubernetesLabels is a map of kubernetes cluster labels used for RBAC.
  • kubernetes_labels_expression (String) KubernetesLabelsExpression is a predicate expression used to allow/deny access to kubernetes clusters.
  • kubernetes_resources (Attributes List) KubernetesResourceMatchers is the set of Kubernetes resources this role grants access to. (see below for nested schema)
  • kubernetes_users (List of String) KubernetesUsers is an optional list of kubernetes users to impersonate.
  • request (Attributes) Request holds allow/deny conditions for access requests. (see below for nested schema)
  • review_requests (Attributes) ReviewRequests defines conditions for submitting access reviews. (see below for nested schema)
  • rules (Attributes List) Rules is a list of rules and their access levels. (see below for nested schema)
  • server_labels (Map of List of String) ServerLabels is a map of server labels used to dynamically grant access to servers.
  • server_labels_expression (String) ServerLabelsExpression is a predicate expression used to allow/deny access to SSH nodes.
  • server_logins (List of String) ServerLogins is a list of *nix system logins.

Nested Schema for spec.allow.impersonate​

Optional:

  • roles (List of String) Roles is a list of resources this role is allowed to impersonate.
  • users (List of String) Users is a list of resources this role is allowed to impersonate.
  • where (String) Where specifies an optional advanced matcher.

Nested Schema for spec.allow.kubernetes_resources​

Optional:

  • kind (String) Kind specifies the Kubernetes Resource type. At the moment only "pod" is supported.
  • name (String) Name is the resource name. It supports wildcards.
  • namespace (String) Namespace is the resource namespace. It supports wildcards.
  • verbs (List of String) Verbs are the allowed Kubernetes verbs for the following resource.

Nested Schema for spec.allow.request​

Optional:

  • annotations (Map of List of String) Annotations is a collection of annotations to be programmatically appended to pending access requests at the time of their creation.
  • claims_to_roles (Attributes List) ClaimsToRoles specifies a mapping from claims (traits) to roles. (see below for nested schema)
  • max_duration (String) MaxDuration is the maximum amount of time the access will be granted for. If this is zero, the default duration is used.
  • roles (List of String) Roles is the name of roles which will match the request rule.
  • search_as_roles (List of String) SearchAsRoles is a list of extra roles which should apply to a user while they are searching for resources as part of a Resource Access Request.
  • suggested_reviewers (List of String) SuggestedReviewers is a list of reviewer suggestions.
  • thresholds (Attributes List) Thresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. (see below for nested schema)

Nested Schema for spec.allow.request.claims_to_roles​

Optional:

  • claim (String) Claim is the claim name.
  • roles (List of String) Roles is the set of AlmaForge roles this mapping resolves to.
  • value (String) Value is the claim value to match.

Nested Schema for spec.allow.request.thresholds​

Optional:

  • approve (Number) Approve is the number of matching approvals needed for state-transition.
  • deny (Number) Deny is the number of denials needed for state-transition.
  • filter (String) Filter is an optional predicate used to determine which reviews count toward this threshold.
  • name (String) Name is the optional human-readable name of the threshold.

Nested Schema for spec.allow.review_requests​

Optional:

  • claims_to_roles (Attributes List) ClaimsToRoles specifies a mapping from claims (traits) to roles. (see below for nested schema)
  • preview_as_roles (List of String) PreviewAsRoles is a list of extra roles which should apply to a reviewer while they are viewing a Resource Access Request.
  • roles (List of String) Roles is the name of roles which may be reviewed.
  • where (String) Where is an optional predicate which further limits which requests are reviewable.

Nested Schema for spec.allow.review_requests.claims_to_roles​

Optional:

  • claim (String) Claim is the claim name.
  • roles (List of String) Roles is the set of AlmaForge roles this mapping resolves to.
  • value (String) Value is the claim value to match.

Nested Schema for spec.allow.rules​

Optional:

  • actions (List of String) Actions specifies optional actions taken when this rule matches.
  • resources (List of String) Resources is a list of resources.
  • verbs (List of String) Verbs is a list of verbs.
  • where (String) Where specifies an optional advanced matcher.

Nested Schema for spec.deny​

Optional:

  • app_labels (Map of List of String) AppLabels is a map of labels used as part of the RBAC system.
  • app_labels_expression (String) AppLabelsExpression is a predicate expression used to allow/deny access to AppTargets.
  • database_labels (Map of List of String) DatabaseLabels are used in RBAC system to allow/deny access to databases.
  • database_labels_expression (String) DatabaseLabelsExpression is a predicate expression used to allow/deny access to DatabaseTargets.
  • database_names (List of String) DatabaseNames is a list of database names this role is allowed to connect to.
  • database_roles (List of String) DatabaseRoles is a list of database roles for automatic user creation.
  • database_service_labels (Map of List of String) DatabaseServiceLabels are used in RBAC system to allow/deny access to Database Services.
  • database_service_labels_expression (String) DatabaseServiceLabelsExpression is a predicate expression used to allow/deny access to Database Services.
  • database_users (List of String) DatabaseUsers is a list of database users this role is allowed to connect as.
  • host_groups (List of String) HostGroups is a list of groups for created users to be added to.
  • host_sudoers (List of String) HostSudoers is a list of entries to include in a user's sudoer file.
  • impersonate (Attributes) Impersonate specifies what users and roles this role is allowed to impersonate by issuing certificates or other possible means. (see below for nested schema)
  • kubernetes_groups (List of String) KubernetesGroups is a list of kubernetes groups.
  • kubernetes_labels (Map of List of String) KubernetesLabels is a map of kubernetes cluster labels used for RBAC.
  • kubernetes_labels_expression (String) KubernetesLabelsExpression is a predicate expression used to allow/deny access to kubernetes clusters.
  • kubernetes_resources (Attributes List) KubernetesResourceMatchers is the set of Kubernetes resources this role grants access to. (see below for nested schema)
  • kubernetes_users (List of String) KubernetesUsers is an optional list of kubernetes users to impersonate.
  • request (Attributes) Request holds allow/deny conditions for access requests. (see below for nested schema)
  • review_requests (Attributes) ReviewRequests defines conditions for submitting access reviews. (see below for nested schema)
  • rules (Attributes List) Rules is a list of rules and their access levels. (see below for nested schema)
  • server_labels (Map of List of String) ServerLabels is a map of server labels used to dynamically grant access to servers.
  • server_labels_expression (String) ServerLabelsExpression is a predicate expression used to allow/deny access to SSH nodes.
  • server_logins (List of String) ServerLogins is a list of *nix system logins.

Nested Schema for spec.deny.impersonate​

Optional:

  • roles (List of String) Roles is a list of resources this role is allowed to impersonate.
  • users (List of String) Users is a list of resources this role is allowed to impersonate.
  • where (String) Where specifies an optional advanced matcher.

Nested Schema for spec.deny.kubernetes_resources​

Optional:

  • kind (String) Kind specifies the Kubernetes Resource type. At the moment only "pod" is supported.
  • name (String) Name is the resource name. It supports wildcards.
  • namespace (String) Namespace is the resource namespace. It supports wildcards.
  • verbs (List of String) Verbs are the allowed Kubernetes verbs for the following resource.

Nested Schema for spec.deny.request​

Optional:

  • annotations (Map of List of String) Annotations is a collection of annotations to be programmatically appended to pending access requests at the time of their creation.
  • claims_to_roles (Attributes List) ClaimsToRoles specifies a mapping from claims (traits) to roles. (see below for nested schema)
  • max_duration (String) MaxDuration is the maximum amount of time the access will be granted for. If this is zero, the default duration is used.
  • roles (List of String) Roles is the name of roles which will match the request rule.
  • search_as_roles (List of String) SearchAsRoles is a list of extra roles which should apply to a user while they are searching for resources as part of a Resource Access Request.
  • suggested_reviewers (List of String) SuggestedReviewers is a list of reviewer suggestions.
  • thresholds (Attributes List) Thresholds is a list of thresholds, one of which must be met in order for reviews to trigger a state-transition. (see below for nested schema)

Nested Schema for spec.deny.request.claims_to_roles​

Optional:

  • claim (String) Claim is the claim name.
  • roles (List of String) Roles is the set of AlmaForge roles this mapping resolves to.
  • value (String) Value is the claim value to match.

Nested Schema for spec.deny.request.thresholds​

Optional:

  • approve (Number) Approve is the number of matching approvals needed for state-transition.
  • deny (Number) Deny is the number of denials needed for state-transition.
  • filter (String) Filter is an optional predicate used to determine which reviews count toward this threshold.
  • name (String) Name is the optional human-readable name of the threshold.

Nested Schema for spec.deny.review_requests​

Optional:

  • claims_to_roles (Attributes List) ClaimsToRoles specifies a mapping from claims (traits) to roles. (see below for nested schema)
  • preview_as_roles (List of String) PreviewAsRoles is a list of extra roles which should apply to a reviewer while they are viewing a Resource Access Request.
  • roles (List of String) Roles is the name of roles which may be reviewed.
  • where (String) Where is an optional predicate which further limits which requests are reviewable.

Nested Schema for spec.deny.review_requests.claims_to_roles​

Optional:

  • claim (String) Claim is the claim name.
  • roles (List of String) Roles is the set of AlmaForge roles this mapping resolves to.
  • value (String) Value is the claim value to match.

Nested Schema for spec.deny.rules​

Optional:

  • actions (List of String) Actions specifies optional actions taken when this rule matches.
  • resources (List of String) Resources is a list of resources.
  • verbs (List of String) Verbs is a list of verbs.
  • where (String) Where specifies an optional advanced matcher.

Nested Schema for spec.options​

Optional:

  • cert_extensions (Attributes List) CertExtensions specifies the key/values to add to the certificate. (see below for nested schema)
  • cert_format (String) CertificateFormat defines the format of the user certificate to allow compatibility with older versions of OpenSSH.
  • client_idle_timeout (String) ClientIdleTimeout sets disconnect clients on idle timeout behavior. If set to 0 means do not disconnect.
  • create_db_user (Boolean) CreateDatabaseUser enables automatic database user creation.
  • create_db_user_mode (String) CreateDatabaseUserMode allows users to be automatically created on a database when not set to off.
  • create_host_user (Boolean) CreateHostUser allows users to be automatically created on a host.
  • create_host_user_mode (String) CreateHostUserMode allows users to be automatically created on a host when not set to off.
  • disconnect_expired_cert (Boolean) DisconnectExpiredCert sets disconnect clients on expired certificates.
  • forward_agent (Boolean) ForwardAgent is SSH agent forwarding.
  • lock (String) Lock specifies the locking mode (strict|bestEffort) to be applied with the role.
  • max_connections (Number) MaxConnections defines the maximum number of concurrent connections a user may hold.
  • max_kubernetes_connections (Number) MaxKubernetesConnections defines the maximum number of concurrent Kubernetes sessions a user may hold.
  • max_session_ttl (String) MaxSessionTTL defines how long an SSH session can last.
  • max_sessions (Number) MaxSessions defines the maximum number of concurrent sessions per connection.
  • permit_x11_forwarding (Boolean) PermitX11Forwarding authorizes use of X11 forwarding.
  • pin_source_ip (Boolean) PinSourceIP forces the same client IP for certificate generation and usage.
  • port_forwarding (Boolean) PortForwarding grants the "permit-port-forwarding" extension in the certificate. Not granted unless set.
  • record_session (Attributes) RecordSession contains the SSH session recording policy. (see below for nested schema)
  • request_access (String) RequestAccess defines the access request strategy (optional|note|always) where optional is the default.
  • request_prompt (String) RequestPrompt is an optional message telling users what they ought to request.
  • ssh_file_copy (Boolean) SSHFileCopy indicates whether remote file operations via SCP or SFTP are allowed over an SSH session.

Nested Schema for spec.options.cert_extensions​

Optional:

  • name (String) Name specifies the key to be used in the cert extension.
  • value (String) Value specifies the value to be used in the cert extension.

Nested Schema for spec.options.record_session​

Optional:

  • default (String) Default indicates the default recording mode for services.
  • ssh (String) SSH indicates the session recording mode used on SSH sessions.

Import​

Create the matching resource block first, then import the existing object's metadata.name. With the example above, the Terraform address and server name are:

Terminal
terraform import almaforge_role.developers developersterraform plan

Use the address from your configuration and the name of the existing object. Import records the object in Terraform state. Review the first plan carefully because omitted fields will reset or clear on apply. The import guide also covers generating configuration from an existing object.