Expression Evaluator

Overview¶

The omctl instance evaluate subcommand introduces a powerful new capability to the Omnistrate CLI, allowing you to evaluate Omnistrate expressions directly within the context of an active deployment or instance.

This feature is designed to significantly accelerate your development and debugging workflows, especially when working with Terraform or Helm charts that rely heavily on Omnistrate expressions and variable references.

Why Use This Feature?¶

Before this command, iterating on changes in your infrastructure code (like Terraform or Helm) that utilized Omnistrate expressions often involved a cycle of deploying, then inspecting logs or outputs to verify expression results. This process could be time-consuming and cumbersome.

With omctl instance evaluate, you can now:

• Rapidly Prototype Expressions: Quickly test and refine your Omnistrate expressions without needing a full deployment cycle.
• Debug Variable References: Instantly check the resolved values of $var (instance-specific variables), $sys (system parameters), and other expression components in a live instance context.
• Validate Configuration: Ensure that your expressions will resolve to the expected values before applying them in your deployment definitions.
• Understand Instance State: Gain immediate insights into the runtime configuration and system parameters of any given instance.

This command transforms the development experience, making it much faster and more efficient to work with Omnistrate's dynamic expression capabilities.

Key Features¶

• Single Expression Support: Evaluate individual expressions directly from the command line.
• Expression File Support: Load and evaluate multiple expressions defined in a JSON file.
• Mutual Exclusivity: Ensure clarity by using either the --expression or --expression-file flag, but not both.
• Full Output Format Support: View results in table, text, or json formats, consistent with other omctl commands.

Usage¶

The evaluate command requires an [instance-id] and a [resource-key].

Evaluate a single expression:

omctl instance evaluate instance-ab1c2d3e terraform-infra --expression "$var.username + {{ $sys.id }}"

Evaluate multiple expressions from a JSON file:

First, create a expressions.json file like this:

{
  "greeting": "'Hello ' + $sys.tenant.name"
}

Then, run the command:

omctl instance evaluate instance-fg4h5i6j helm-chart --expression-file expressions.json

Specify output format:

omctl instance evaluate instance-kl7m8n9o terraform-infra --expression "test" --output json

Arguments and Flags¶

• [instance-id] (Required): The unique identifier of the instance you want to evaluate expressions against.
• [resource-key] (Required): The key of the resource within the instance where the expressions will be evaluated.
• --expression, -e: (String) The expression string to evaluate. Use this for single expressions.
• --expression-file, -f: (Path) Path to a JSON file containing a map of expressions to evaluate. Use this for multiple expressions.
• --output, -o: (String) The desired output format: table, text, or json. (Inherited from global flags)

Output Formats¶

The output format adapts based on the --output flag.

For a single expression:

{
    "result": "evaluated_value_here"
}

For expression maps:

{
    "result": {
        "greeting": "Hello Jane Doe"
    }
}

Examples¶

Here are some practical examples of using omctl instance evaluate:

Evaluate system parameters:

➜ omctl instance evaluate instance-qr0s1t2u terraform-infra --expression '$sys.deploymentCell.oidcIssuerID' -o json | jq
{
  "result": "eastus2.oic.prod-aks.azure.com/1a2b3c4d-e5f6-7g8h-9i0j-1k2l3m4n5o6p/7q8r9s0t-1u2v-3w4x-5y6z-7a8b9c0d1e2f/"
}

Evaluate expressions to check instance deployment parameters:

➜ omctl instance evaluate instance-vw3x4y5z helm-chart --expression '$var.gpu_enabled' -o json | jq
{
  "result": true
}

Evaluate complex expressions combining variables and system parameters:

❯ omctl instance evaluate instance-j8k9l0m1 helm-chart --expression 'GPU Enabled: {{ $var.gpu_enabled }} on {{ $sys.deploymentCell.cloudProviderName }} for {{ $sys.tenant.name }}' -o json | jq
{
  "result": "GPU Enabled: true on aws for Jane Doe"
}