Overview
Identity (also known as a workload identity) is one of the four Control Plane principal types (users, service accounts, groups, and identities).
A workload needing to consume cloud resources from one or more cloud providers (e.g., AWS, Azure, and GCP) without storing credentials or needing to communicate to endpoints within a private network - must be assigned an identity.
An identity is a named object that allows an authorized administrator to define:
- Least-privilege access rules allowed on cloud resources across cloud providers. Each identity can reference only one cloud account per provider. For example, you can have one account in Azure and one account in GCP, but not two different accounts in GCP within the same identity. You define access policies granted to the identity for each cloud provider you need to use (one, two, or all three clouds, depending on your workload requirements).
- Network traversal rules from workloads into specific endpoints in private networks (e.g., a VPC). These rules connect an agent in a private network to the Control Plane infrastructure, allowing workloads to selectively access TCP endpoints inside private networks where agents are installed and running.
- Provides secure, private connectivity from a workload to cloud-hosted services across AWS (vpc endpoints) and GCP (private service connect) without traversing the public internet. It leverages cloud provider-specific private networking services to route traffic over internal infrastructure. This enables low-latency, secure communication to private resources while maintaining strict network isolation and identity-based access control.
An identity is scoped to a GVC and can be assigned to multiple workloads within the same GVC that needs the same cloud resources and network access.
A workload can be assigned exactly one identity. An identity is only required when a workload needs to consume cloud resources without embedding credentials and/or when a workload needs to consume resources in a private network such as a VPC. If neither is required, a workload can operate without assigning it an identity.
Once configured, an identity assigned to a workload enables it to:
- Access specific resources of AWS, Azure, and/or GCP
- Access private network resources from external cloud accounts, data centers or any other private network. (Tunneling network traffic from workloads to specific TCP hosts and ports is facilitated using agents. This capability is referred to as “wormholes”.)
- Access the NATS NGS service using scoped credentials automatically supplied at runtime
Identities are powerful Control Plane resources that can be granted any permission to your cloud environment. The ability to create identities should only be given to administrators by using a policy. Create an Identity
Refer to the Create an Identity guide for additional details.
Identity Specification
An identity can be configured with the following fields:
Cloud Provider Access
AWS Identity (aws)
| Field | Type | Required | Description |
|---|
cloudAccountLink | string | Yes | Link to the AWS cloud account |
roleName | string | No* | AWS role name to reuse (max 64 chars) |
policyRefs | array | No* | Array of policy references |
trustPolicy | object | No | AWS trust policy document |
roleName OR policyRefs is required, but not both.
Trust Policy Structure:
trustPolicy:
Version: "2012-10-17" # Optional, defaults to "2012-10-17"
Statement:
- # Policy statement objects
GCP Identity (gcp)
| Field | Type | Required | Description |
|---|
cloudAccountLink | string | Yes | Link to the GCP cloud account |
serviceAccount | string | No* | Existing service account email (must end with .gserviceaccount.com) |
bindings | array | No* | Array of role bindings |
scopes | array | No | OAuth scopes (defaults to ["https://www.googleapis.com/auth/cloud-platform"]) |
serviceAccount OR bindings is required, but not both.
Binding Structure:
bindings:
- resource: "projects/my-project" # Optional, defaults to project
roles:
- "roles/storage.objectViewer"
- "roles/bigquery.dataViewer"
Azure Identity (azure)
| Field | Type | Required | Description |
|---|
cloudAccountLink | string | Yes | Link to the Azure cloud account |
roleAssignments | array | Yes | Array of role assignments |
roleAssignments:
- scope: "/subscriptions/123/resourceGroups/my-rg" # Optional, defaults to subscription
roles:
- "Reader"
- "Storage Blob Data Reader"
NATS Identity (ngs)
| Field | Type | Required | Description |
|---|
cloudAccountLink | string | Yes | Link to the NATS cloud account |
pub | object | No | Publish permissions |
sub | object | No | Subscribe permissions |
resp | object | No | Response permissions |
subs | number | No | Max subscriptions per connection (default: -1, no limit) |
data | number | No | Max bytes a connection can send (default: -1, no limit) |
payload | number | No | Max message payload (default: -1, no limit) |
pub:
allow: ["orders.*", "users.>"]
deny: ["orders.sensitive.*"]
sub:
allow: ["orders.*", "users.>"]
deny: ["orders.sensitive.*"]
resp:
max: 1 # Number of responses allowed (-1 = no limit)
ttl: "30s" # Deadline format: #ms, #s, #m, #h
Private Network Access
Network Resources (networkResources)
| Field | Type | Required | Description |
|---|
name | string | Yes | Resource name or domain |
agentLink | string | No | Link to the agent |
IPs | array | No* | Array of IPv4 addresses (1-5 addresses) |
FQDN | string | No* | Fully qualified domain name |
resolverIP | string | No | IPv4 resolver address |
ports | array | Yes | Array of ports (1-10 ports, 0-65535) |
IPs OR FQDN is required.
All agents referenced in an identity must be the same protocol version (v1 or v2).
Native Network Resources (nativeNetworkResources)
| Field | Type | Required | Description |
|---|
name | string | Yes | Resource name or domain |
FQDN | string | No | Fully qualified domain name |
ports | array | Yes | Array of ports (1-10 ports, 0-65535) |
awsPrivateLink | object | No* | AWS PrivateLink configuration |
gcpServiceConnect | object | No* | GCP Service Connect configuration |
awsPrivateLink OR gcpServiceConnect is required.
AWS PrivateLink Structure:
awsPrivateLink:
endpointServiceName: "com.amazonaws.vpce.us-east-1.vpce-svc-12345678"
gcpServiceConnect:
targetService: "projects/my-project/regions/us-central1/serviceAttachments/my-service"
Status
| Field | Type | Required | Description |
|---|
status | object | No | Provider status information |
status.objectName | string | No | Object name |
status.aws | object | No | AWS provider status |
status.gcp | object | No | GCP provider status |
status.azure | object | No | Azure provider status |
status:
objectName: "my-identity"
aws:
lastError: "Error message if any"
usable: true
gcp:
lastError: null
usable: true
azure:
lastError: null
usable: false
Additional Fields
| Field | Type | Required | Description |
|---|
gvc | string | No | Parent GVC (used by local tools, ignored by server) |
Example YAML
Here’s a comprehensive example showing all identity types and configurations:
# Multi-cloud identity with all provider types
name: "multi-cloud-workload-identity"
description: "Identity for workload accessing AWS, GCP, Azure, and NATS resources"
tags:
environment: "production"
team: "platform"
# AWS Identity - using policy references
aws:
cloudAccountLink: "/org/my-org/cloudaccount/aws-prod"
policyRefs:
- "aws::arn:aws:iam::123456789012:policy/S3ReadOnly"
- "aws::arn:aws:iam::123456789012:policy/DynamoDBReadOnly"
trustPolicy:
Version: "2012-10-17"
Statement:
- Effect: "Allow"
Principal:
Service: "ec2.amazonaws.com"
Action: "sts:AssumeRole"
# GCP Identity - using role bindings
gcp:
cloudAccountLink: "/org/my-org/cloudaccount/gcp-prod"
bindings:
- resource: "projects/my-gcp-project"
roles:
- "roles/storage.objectViewer"
- "roles/bigquery.dataViewer"
- "roles/pubsub.subscriber"
scopes:
- "https://www.googleapis.com/auth/cloud-platform"
- "https://www.googleapis.com/auth/bigquery"
# Azure Identity
azure:
cloudAccountLink: "/org/my-org/cloudaccount/azure-prod"
roleAssignments:
- scope: "/subscriptions/12345678-1234-1234-1234-123456789012/resourceGroups/my-rg"
roles:
- "Reader"
- "Storage Blob Data Reader"
- scope: "/subscriptions/12345678-1234-1234-1234-123456789012"
roles:
- "Contributor"
# NATS Identity
ngs:
cloudAccountLink: "/org/my-org/cloudaccount/nats-prod"
pub:
allow: ["orders.*", "users.>", "notifications.*"]
deny: ["orders.sensitive.*", "users.admin.*"]
sub:
allow: ["orders.*", "users.>", "responses.>"]
deny: ["orders.sensitive.*"]
resp:
max: 5
ttl: "30s"
subs: 100
data: 1048576 # 1MB
payload: 65536 # 64KB
# Network Resources (Cloud Wormhole)
networkResources:
- name: "database-server"
agentLink: "/org/my-org/agent/db-agent"
IPs: ["10.0.1.100", "10.0.1.101"]
ports: [5432, 3306]
resolverIP: "10.0.1.1"
- name: "api-gateway"
FQDN: "api.internal.company.com"
ports: [443, 8080]
- name: "cache-cluster"
agentLink: "/org/my-org/agent/cache-agent"
IPs: ["10.0.2.50"]
ports: [6379, 11211]
# Native Network Resources
nativeNetworkResources:
- name: "aws-rds-proxy"
FQDN: "rds-proxy.us-east-1.amazonaws.com"
ports: [5432]
awsPrivateLink:
endpointServiceName: "com.amazonaws.vpce.us-east-1.vpce-svc-12345678abcdef"
- name: "gcp-cloud-sql"
FQDN: "my-project:us-central1:my-instance"
ports: [5432]
gcpServiceConnect:
targetService: "projects/my-project/regions/us-central1/serviceAttachments/my-service"
# Status (read-only, set by system)
status:
objectName: "multi-cloud-workload-identity"
aws:
lastError: null
usable: true
gcp:
lastError: null
usable: true
azure:
lastError: "Authentication failed"
usable: false
Alternative AWS Identity Example (using existing role)
# AWS Identity - reusing existing role
aws:
cloudAccountLink: "/org/my-org/cloudaccount/aws-prod"
roleName: "MyExistingRole"
Alternative GCP Identity Example (using existing service account)
# GCP Identity - using existing service account
gcp:
cloudAccountLink: "/org/my-org/cloudaccount/gcp-prod"
serviceAccount: "my-service-account@my-project.iam.gserviceaccount.com"
scopes:
- "https://www.googleapis.com/auth/cloud-platform"
Permissions
The permissions below are used to define policies together with one or more of the four
principal types:
| Permission | Description | Implies |
|---|
| create | Create new identities | |
| delete | Delete existing identities | |
| edit | Modify existing identities | view |
| manage | Full access | create, delete, edit, manage, use, view |
| use | Refer to this identity from other entities (workload, etc) | view |
| view | Read-only access | |
Access Report
Displays the permissions granted to principals for the identity.
CLI
To view the CLI documentation for Identities, click here.
