Installation

• 1: Prerequisites
• 2: Install

1 - Prerequisites

Required tools, cloud permissions, and Kubernetes cluster configuration for deployment on Amazon EKS or Azure Kubernetes Service (AKS).

Ensure the following prerequisites are met:

Tools

Install and configure the following tools on the host from which you run the installation:

Install the CLI for your cloud provider:

• AWS
• Azure

Cloud Setup

Ensure that the following requirements are met:

• A Protegrity Provisioned Cluster (PPC) is available. For more information about PPC, refer to Protegrity Provisioned Cluster.
• The host from which you run the installation can connect to the required registry. If you are not already authenticated, log in to it.

Configure cloud credentials for your provider:

• AWS
• Azure

To authenticate to the Protegrity Container Registry, use the following command with credentials from the My.Protegrity portal during account creation:

echo "<password>" | helm registry login <Container_Registry_Path> --username "<username>" --password-stdin

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

Note: helm registry login authenticates Helm only. The OpenTofu module is pulled from the OCI registry and additionally requires container registry credentials in ~/.config/containers/auth.json. You configure these during the Install procedure before running tofu init.

Cluster Requirements

A standard Protegrity Provisioned Cluster (PPC) already satisfies the following requirements, so no additional setup is needed in that case. Use the checklist below to verify the cluster only if you are not deploying onto a standard PPC cluster.

• AWS
• Azure

External Service Prerequisites

The umbrella chart deploys Sensitive Data Guardrails, Vault-Based Tokenization, and Semantic Guardrails as part of the release. The Classification Service must already be available in the cluster:

Note: AI Gateway does not require cloud object storage, such as an S3 bucket or Azure Storage Account, or dedicated cloud data-access roles. The OpenTofu module provisions only the node isolation resources for workload scheduling.

Cloud Permissions for Installation

• AWS
• Azure

2 - Install

This section deploys the AI Gateway umbrella chart on a supported Kubernetes cluster, either Amazon EKS or Azure Kubernetes Service (AKS). OpenTofu provisions node isolation resources and writes a federated-guardrails-values.yaml file with scheduling overrides. Helm then deploys the full stack using that file.

The chart renders the scanner and routing configuration from policyConfig.policyYaml. The gateway retrieves the authoritative Cedar policy from Policy during startup and, when configured, refreshes it on a background interval.

Deployment Steps

Complete the prerequisites before starting. Then complete the following steps in order, selecting the tab for your cloud provider.

1. Provision Cloud Infrastructure with OpenTofu

The OpenTofu module sets up workload scheduling for each cloud and creates federated-guardrails-values.yaml with Helm settings. For AWS, it also creates the Karpenter EC2NodeClass and NodePool. For AKS, use the Azure module instead of the AWS configuration.

Configure OCI Registry Credentials

The OpenTofu module is pulled from the OCI registry, which requires container registry credentials in ~/.config/containers/auth.json. helm registry login authenticates Helm only and does not create this file, so configure these credentials before running tofu init.

1. Run the following command to create the configuration directory.

   mkdir -p ~/.config/containers
   

2. Obtain the username and access token from the My.Protegrity portal. For more information about obtaining the credentials from the My.Protegrity portal, refer to the section Configuring Authentication for Protegrity AI Team Edition.

3. Generate base64 encoded string with padding for username:accesstoken obtained from the My.Protegrity portal.

   Ensure that you specify the username and access token within single quotes when generating the base64 encoded value. For example, 'username:accesstoken'.

   Note: For the Protegrity Container Registry, set <Container_Registry_Path> to registry.protegrity.com:9443. For a local registry, set it to the local registry endpoint.

4. Create a file named ~/.config/containers/auth.json with the following content.

   {
       "auths": {
           "<Container_Registry_Path>": {
               "auth": "<base64 generated string from step-3>"
           }
       }
   }
   

Configure cloud access, create a directory with a single main.tf for your cloud provider, and then run the OpenTofu commands. Run the OpenTofu and Helm commands from that directory, keeping the same shell session so that your cloud environment variables remain available.

• AWS
• Azure

aws sts get-caller-identity

terraform {
  required_version = "~> 1.10"

  required_providers {
    aws = {
      source  = "registry.opentofu.org/hashicorp/aws"
      version = "~> 5.0"
    }
    kubernetes = {
      source  = "registry.opentofu.org/hashicorp/kubernetes"
      version = "~> 2.35"
    }
  }
}

variable "cluster_name" {
  type        = string
  description = "EKS cluster name."
}

variable "environment" {
  type    = string
  default = "production"
}

data "aws_eks_cluster" "this" {
  name = var.cluster_name
}

data "aws_eks_cluster_auth" "this" {
  name = var.cluster_name
}

provider "kubernetes" {
  host                   = data.aws_eks_cluster.this.endpoint
  cluster_ca_certificate = base64decode(data.aws_eks_cluster.this.certificate_authority[0].data)
  token                  = data.aws_eks_cluster_auth.this.token
}

module "federated_guardrails" {
  source = "oci://<Container_Registry_Path>/federated-guardrails/federated-guardrails/opentofu/federated-guardrails?tag=aws-1.0.0"

  cluster_name  = var.cluster_name
  oci_host      = "<Container_Registry_Path>"
  environment   = var.environment
  chart_version = "1.0.0"
}

output "helm_install" {
  value = module.federated_guardrails.helm_install
}

tofu init
tofu plan -var="cluster_name=<CLUSTER_NAME>"
tofu apply -var="cluster_name=<CLUSTER_NAME>"

az login

az account set --subscription "{{SUBSCRIPTION_ID}}"

export ARM_SUBSCRIPTION_ID="{{SUBSCRIPTION_ID}}"

az account show --query '{subscriptionId:id, subscriptionName:name}' --output table
az aks show \
  --resource-group "{{RESOURCE_GROUP}}" \
  --name "{{CLUSTER_NAME}}" \
  --query '{name:name, resourceGroup:resourceGroup, provisioningState:provisioningState}' \
  --output table

terraform {
  required_version = "~> 1.10"

  required_providers {
    azurerm = {
      source  = "registry.opentofu.org/hashicorp/azurerm"
      version = "~> 5.7"
    }
    kubernetes = {
      source  = "registry.opentofu.org/hashicorp/kubernetes"
      version = "~> 2.35"
    }
  }
}

variable "cluster_name" {
  type        = string
  description = "AKS cluster name."
}

variable "resource_group_name" {
  type        = string
  description = "Azure resource group that contains the AKS cluster."
}

variable "environment" {
  type    = string
  default = "production"
}

provider "azurerm" {
  features {}
  resource_provider_registrations = "none"
}

data "azurerm_kubernetes_cluster" "this" {
  name                = var.cluster_name
  resource_group_name = var.resource_group_name
}

provider "kubernetes" {
  host                   = data.azurerm_kubernetes_cluster.this.kube_config[0].host
  client_certificate     = base64decode(data.azurerm_kubernetes_cluster.this.kube_config[0].client_certificate)
  client_key             = base64decode(data.azurerm_kubernetes_cluster.this.kube_config[0].client_key)
  cluster_ca_certificate = base64decode(data.azurerm_kubernetes_cluster.this.kube_config[0].cluster_ca_certificate)
}

module "federated_guardrails" {
  source = "oci://<Container_Registry_Path>/federated-guardrails/federated-guardrails/opentofu/federated-guardrails?tag=azure-1.0.0"

  cluster_name        = var.cluster_name
  resource_group_name = var.resource_group_name
  oci_host            = "<Container_Registry_Path>"
  environment         = var.environment
  chart_version       = "1.0.0"
}

output "helm_install" {
  value = module.federated_guardrails.helm_install
}

tofu init
tofu plan \
  -var="cluster_name={{CLUSTER_NAME}}" \
  -var="resource_group_name={{RESOURCE_GROUP}}"
tofu apply \
  -var="cluster_name={{CLUSTER_NAME}}" \
  -var="resource_group_name={{RESOURCE_GROUP}}"

Verify that federated-guardrails-values.yaml exists in the working directory. Display the generated Helm command:

tofu output -raw helm_install

Confirm that the command uses the intended chart version and namespace. Use the generated values file in the Helm deployment that follows.

Module variables

• AWS
• Azure

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

2. Deploy with Helm

The OpenTofu module writes a federated-guardrails-values.yaml file in the working directory. The chart defaults to an OpenAI upstream. Use an OpenAI API key for that default, or configure a different upstream in the policy. If you do not have a key during installation, use a placeholder and replace it before sending requests to the upstream LLM. The value is required only on the first install and is preserved automatically on upgrades.

The Helm commands are the same for AWS and Azure. Use the values file generated by the module for your cloud provider.

1. Configure the kubectl context for the target cluster:

• AWS
• Azure

aws eks update-kubeconfig \
  --region {{AWS_REGION}} \
  --name {{CLUSTER_NAME}}

az aks get-credentials \
  --resource-group "{{RESOURCE_GROUP}}" \
  --name "{{CLUSTER_NAME}}"

Verify that the current context points to the target cluster:

kubectl config current-context
kubectl get nodes

Confirm that the context identifies the intended cluster and that its nodes are Ready before continuing.

2. Authenticate to the container registry before running any Helm command:

helm registry login <Container_Registry_Path>

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

3. Configure the Policy endpoint and synchronization interval in the federated-guardrails-values.yaml file that the OpenTofu run generated in the working directory. Add the following block at the top level of the file. If a federated-guardrails: key already exists, merge the environment entries into it instead of adding a second key:

federated-guardrails:
  environment:
    FG_POLICY_SYNC_URL: "http://policy-api-service.pty-policy.svc.cluster.local:8000/pty/policy/v1.0/product-policies/federated-guardrails"
    FG_POLICY_POLL_INTERVAL_S: "60"

Policy must publish the Cedar policy for the federated-guardrails product. The gateway validates and caches the active policy in memory.

Note: FG_POLICY_SYNC_URL and FG_POLICY_POLL_INTERVAL_S control the synchronization for Policy.

4. Install the chart. On the first install, provide the upstream API key with --set:

export FG_UPSTREAM_API_KEY="placeholder-update-before-use"

helm upgrade --install federated-guardrails \
  oci://<Container_Registry_Path>/federated-guardrails/federated-guardrails/helm/federated-guardrails \
  --version 1.0.0 \
  --namespace federated-guardrails --create-namespace \
  --values federated-guardrails-values.yaml \
  --set federated-guardrails.auth.apiKey="$FG_UPSTREAM_API_KEY"

For upgrades, omit the --set flag because the API key is already stored in the cluster secret:

helm upgrade federated-guardrails \
  oci://<Container_Registry_Path>/federated-guardrails/federated-guardrails/helm/federated-guardrails \
  --version 1.0.0 \
  --namespace federated-guardrails \
  --values federated-guardrails-values.yaml

Note: If deploying from the Protegrity Container Registry, use registry.protegrity.com:9443. Specify the local registry endpoint if a local registry is used.

3. Monitor

1. Monitor the deployment process using the following command:

kubectl get pods -n federated-guardrails

Verify that all pods are in the Running state. The following is a sample output:

NAME                                                   READY   STATUS    RESTARTS   AGE
federated-guardrails-<hash>                            1/1     Running   0          3m10s
federated-guardrails-sensitive-data-guardrails-<hash>  1/1     Running   0          3m10s
federated-guardrails-vault-based-tokenization-<hash>   1/1     Running   0          3m10s
federated-guardrails-valkey-0                          1/1     Running   0          3m10s
federated-guardrails-valkey-1                          1/1     Running   0          3m10s
federated-guardrails-valkey-2                          1/1     Running   0          3m10s

2. Verify that all services are deployed.

kubectl get svc -n federated-guardrails

3. Run health checks for each component.

# AI Gateway
kubectl exec -n federated-guardrails deploy/federated-guardrails -- \
  curl -s http://localhost:8080/pty/federated-guardrails/v1/health

# Sensitive Data Guardrail
kubectl exec -n federated-guardrails deploy/federated-guardrails-sensitive-data-guardrails -- \
  curl -s http://localhost:8080/pty/sensitive-data-guardrails/v1/health

# Vault-Based Tokenization
kubectl exec -n federated-guardrails deploy/federated-guardrails-vault-based-tokenization -- \
  curl -s http://localhost:8000/api/v1/version

For more information about connecting client applications to the gateway, refer to Connecting to the Gateway.