Customer Variables

Customer Variables are a secure storage mechanism for sensitive information required during the image build process. They allow you to inject secrets, license keys, and configuration parameters into your custom components without exposing them in plain text within your template definitions.

Overview

Variables are scoped to a specific customer and are stored using industry-standard encryption. Once a variable is created, its value is never returned by the API. Only the variable's name and a hash of its value are visible in responses, ensuring that your secrets remain protected even from users with view-only access.

Use Cases

• Component Secrets: Provide API keys, service credentials, or license keys to custom shell or Ansible components.
• Azure Trusted Launch: Store UEFI signing keys (PK, KEK, db) required for Azure Trusted Launch configurations.
• Environment Endpoints: Define internal service URLs that vary between different customer environments.

Variable Properties

Property	Constraints	Description
Name	3-120 characters	Unique identifier. Must be alphanumeric with underscores.
Value	1-4096 characters	The sensitive content to be stored securely.

Validation Rules

• Naming Convention: Variable names should follow a consistent pattern, such as APP_LICENSE_KEY or DB_CONNECTION_STRING.
• Uniqueness: Variable names must be unique within a customer's scope. Attempting to create a variable with an existing name will result in a validation error.
• Immutability: To change a variable's value, you must delete the existing variable and recreate it with the new value.

Using Variables in Components

You can reference customer variables within the properties of your template components. When the build process starts, ImageFactory retrieves the encrypted value and injects it into the build environment.

Component Property Reference

In your template definition, you can map a component property to a customer variable by using the variable's name.

{
  "componentId": "custom-script-id",
  "properties": [
    {
      "name": "LICENSE_KEY",
      "value": "CUSTOMER_VARIABLE_NAME"
    }
  ]
}

Azure UEFI Keys

For Azure templates using Trusted Launch, you reference variables in the additionalSignatures section of the provider configuration.

{
  "trustedLaunch": true,
  "additionalSignatures": {
    "uefiKeys": [
      {
        "type": "PK",
        "variableName": "AZURE_UEFI_PK_CERT"
      }
    ]
  }
}

Managing Variables

To manage customer variables, navigate to Variables in the sidebar. From here you can view existing variable names (values are never displayed), create new variables, and delete variables that are no longer needed.

For a detailed walkthrough, see the Variables & Audit Logs guide.

Via API

Variables can also be managed programmatically through the GraphQL API.

Creating a Variable

Use the createVariable mutation to store a new secret.

mutation CreateVariable($input: CreateVariableInput!) {
  createVariable(input: $input) {
    id
    name
    hash
  }
}

Variables:

{
  "input": {
    "name": "NEXUS_API_TOKEN",
    "value": "prod-secret-token-12345"
  }
}

Listing Variables

Retrieve a list of all variables defined for the current customer. Note that the value field is not available in the schema for queries.

query ListVariables {
  variables {
    id
    name
    hash
    createdAt
  }
}

Deleting a Variable

Remove a variable when it is no longer needed.

mutation DeleteVariable($id: ID!) {
  deleteVariable(id: $id)
}

Security Considerations

• Least Privilege: Only grant VIEW permissions on the VARIABLE resource to users who need to know which variables exist. Grant CREATE and DELETE permissions only to authorized security administrators.
• Audit Logs: Every creation and deletion of a variable is recorded in the audit logs, including the identity of the user who performed the action.
• Rotation: Regularly rotate sensitive secrets by deleting the old variable and creating a new one with the updated value. Ensure that any templates referencing the variable are rebuilt to pick up the new secret.