> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensor9.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Permissions Model
Tensor9's permissions model defines how your control plane interacts with customer appliances. Since appliances run in customer-owned infrastructure, permissions govern what operations the control plane can perform, when it can perform them, and how customers approve or audit those operations.
## Permissions context
When deploying applications through Tensor9:
* **Customer appliances** run entirely in the customer's cloud account or private infrastructure
* **Your control plane** orchestrates deployments and operations from your vendor account
* **Permissions** control what your control plane can do within each customer's appliance
The permissions model balances operational capability (your ability to deploy and operate) with customer control (their ability to approve, audit, and restrict access).
## Four-phase permissions model
Tensor9 uses a four-phase permissions model where different lifecycle phases require different permission levels:
| Phase | Purpose | Permission Level | Customer Control |
| ---------------- | ----------------------------------------------------- | ------------------------------------------ | ---------------------------------------- |
| **Install** | Initial appliance setup, major infrastructure changes | Highest (full infrastructure provisioning) | Customer-approved, one-time or rare |
| **Steady-state** | Observability, monitoring, read-only operations | Minimal (read-only) | Active by default (customer can disable) |
| **Deploy** | Deployments, updates, configuration changes | Elevated (read-write on vendor resources) | Customer-approved, time-bounded |
| **Operate** | Remote operations, troubleshooting, debugging | Elevated (read-write for debugging) | Customer-approved, time-bounded |
Each phase corresponds to an IAM role (in cloud environments) or service account (in Kubernetes environments) with specific permissions scoped to that phase's requirements.
## Install permissions
Install permissions are the highest level of permissions, used for initial appliance setup or major infrastructure changes:
### What install permissions allow
* **Full infrastructure provisioning**: Create VPCs, networking, IAM roles, databases, and all application resources
* **Initial configuration**: Set up observability forwarding, secrets management, DNS
* **Major upgrades**: Perform infrastructure migrations or significant architectural changes
### When install permissions are used
* **Initial appliance provisioning**: When Tensor9 first creates a customer appliance
* **Major version upgrades**: When a new release requires fundamental infrastructure changes
* **Infrastructure migrations**: When moving to a different cloud region or architecture
Install permissions are rarely used after initial setup. Most deployments use deploy permissions, not install permissions.
### Access control
Install permissions are typically:
* **Explicitly approved** by the customer for each use
* **Time-bounded** to a specific maintenance window
* **Audited** with full CloudTrail or audit logging
* **Assumed directly** by authorized operators, not via role chaining
## Steady-state permissions
Steady-state permissions are the baseline permissions your control plane uses for automated observability collection:
### What steady-state permissions allow
* **Observability**: Collect logs, metrics, and traces from the appliance
* **Monitoring**: Read resource state, health checks, and configuration for observability
* **Discovery**: Enumerate deployed resources and their status for telemetry collection
### What steady-state permissions prevent
* Modifying infrastructure (creating, updating, or deleting resources)
* Changing IAM policies or security configurations
* Accessing customer data or application secrets
* Performing destructive operations
Steady-state permissions are active by default - unless a customer disables them. Your control plane uses these permissions continuously to maintain observability and report appliance status.
### Implementation
In AWS, steady-state permissions are implemented as an IAM role that your control plane assumes:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"logs:DescribeLogGroups",
"logs:DescribeLogStreams",
"logs:GetLogEvents",
"cloudwatch:GetMetricData",
"cloudwatch:ListMetrics",
"ec2:Describe*",
"rds:Describe*",
"s3:ListBucket"
],
"Resource": "*"
},
{
"Effect": "Deny",
"Action": [
"iam:*",
"*:Delete*",
"*:Terminate*"
],
"Resource": "*"
}
]
}
```
The role includes explicit denies for destructive or privilege-escalating actions.
## Deploy permissions
Deploy permissions are elevated permissions required for deployments, updates, and configuration changes:
### What deploy permissions allow
* **Infrastructure changes**: Create, update, and delete vendor-owned resources
* **Deployments**: Apply Terraform/CloudFormation changes to the appliance
* **Configuration updates**: Modify application configuration, environment variables
* **Scaling operations**: Adjust compute, storage, or other resource capacity
### What deploy permissions prevent
* Modifying customer IAM policies or roles
* Changing network boundaries or security groups outside vendor resources
* Accessing resources not owned by the vendor application
### Conditional access
Deploy permissions are not continuously active. Your control plane can only assume the deploy role when specific conditions are met:
1. **Customer approval**: The customer grants temporary deploy access
2. **Time-bounded**: Deploy access expires after a defined window (e.g., 1 hour)
3. **Tagged requests**: Assumption requests include specific tags that customers validate
#### Example: AWS conditional assume role
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::VENDOR_ACCOUNT:role/SteadyStateRole"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:RequestTag/DeployAccess": "enabled"
},
"DateLessThan": {
"aws:CurrentTime": "2024-12-31T23:59:59Z"
}
}
}
]
}
```
The steady-state role can only assume the deploy role when:
* The `DeployAccess` tag is set to "enabled"
* The current time is within the allowed window
Customers control when and for how long deploy access is granted.
### Deployment workflow
Customer approves a deployment (manually or via automated approval workflow). This sets the `DeployAccess` tag and defines a time window.
Your control plane assumes the deploy role using the steady-state role. The assumption succeeds because the conditions are met.
Your control plane performs the deployment (e.g., `terraform apply`) using deploy permissions. Infrastructure changes are applied to the appliance.
After the time window expires, the deploy role can no longer be assumed. Control plane reverts to steady-state permissions.
## Operations permissions
Operations permissions control what operations commands your control plane can execute on appliances:
### Operations types
All operations require Operate permissions. Steady-state permissions only allow automated observability collection (logs, metrics, traces), not interactive operations or queries.
| Operation Type | Example | Permission Required |
| -------------------------- | --------------------------------------------------------------- | -------------------------------- |
| **Read-only operations** | `kubectl get pods`, `kubectl describe`, database SELECT queries | Operate |
| **Non-destructive write** | Restart a pod, drain a node, clear cache | Operate |
| **Resource modifications** | Scale a deployment, update a config, database UPDATE queries | Operate |
| **Destructive operations** | Delete resources, terminate instances, DROP tables | Operate (with customer approval) |
### Customer approval for operations
Customers can require approval for operations commands:
```bash theme={null}
# Vendor initiates an operation
tensor9 ops kubectl \
-appName my-app \
-customerName acme-corp \
-originResourceId "aws_eks_cluster.main_cluster" \
-command "kubectl rollout restart deployment/api"
# Output:
# Operation request submitted. Waiting for customer approval...
# Approval granted by jane@acme-corp.com
# Executing: kubectl rollout restart deployment/api
# deployment.apps/api restarted
```
Customers see the exact command before approving, providing full transparency.
## Operate permissions
Operate permissions are elevated permissions required for remote operations, troubleshooting, and debugging:
### What operate permissions allow
* **Remote command execution**: Execute kubectl commands, database queries, and cloud CLI commands
* **Interactive access**: Create ops endpoints for kubectl, SSH, and database access
* **Resource inspection**: Read detailed resource state, logs, and configurations
* **Troubleshooting operations**: Restart pods, run diagnostic commands, query databases
* **Debugging access**: SSH into VMs, exec into containers, run queries against databases
### What operate permissions prevent
* Modifying infrastructure definitions or Terraform state
* Deploying new application versions or configuration changes
* Changing IAM policies or roles
* Accessing resources not owned by the vendor application
* Permanent infrastructure modifications (changes are operational, not persistent)
### Conditional access
Operate permissions are not continuously active. Your control plane can only assume the operate role when specific conditions are met:
1. **Customer approval**: The customer grants temporary operate access
2. **Time-bounded**: Operate access expires after a defined window (e.g., 1 hour)
3. **Tagged requests**: Assumption requests include specific tags that customers validate
#### Example: AWS conditional assume role
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::VENDOR_ACCOUNT:role/SteadyStateRole"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:RequestTag/OperateAccess": "enabled"
},
"DateLessThan": {
"aws:CurrentTime": "2024-12-31T23:59:59Z"
}
}
}
]
}
```
The steady-state role can only assume the operate role when:
* The `OperateAccess` tag is set to "enabled"
* The current time is within the allowed window
Customers control when and for how long operate access is granted.
### Operations workflow
Customer approves an operations request (manually or via automated approval workflow). This sets the `OperateAccess` tag and defines a time window.
Your control plane assumes the operate role using the steady-state role. The assumption succeeds because the conditions are met.
Your control plane performs the operation (e.g., `tensor9 ops kubectl`, `tensor9 ops endpoint create`) using operate permissions. Commands are executed in the appliance.
After the time window expires, the operate role can no longer be assumed. Control plane reverts to steady-state permissions.
## Customer approval workflows
Customers can configure approval workflows that gate access to elevated permissions:
### Manual approval
Customer administrators manually approve deployment requests:
1. Vendor initiates a deployment through the control plane
2. Customer receives a notification (email, Slack, PagerDuty)
3. Customer reviews the deployment details
4. Customer grants deploy access by setting the approval tag
5. Deployment proceeds
### Automated approval
Your customers can automate approvals using their cloud provider's access control features. In AWS, this is done using IAM condition keys directly in the trust policy. For example, to allow deploy role assumptions only during business hours:
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::VENDOR_ACCOUNT:role/SteadyStateRole"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:RequestTag/DeployAccess": "enabled"
},
"DateGreaterThan": {
"aws:CurrentTime": "2024-01-01T09:00:00Z"
},
"DateLessThan": {
"aws:CurrentTime": "2024-01-01T17:00:00Z"
},
"StringEquals": {
"aws:RequestedRegion": "us-east-1"
}
}
}
]
}
```
For more complex automation (e.g., different windows for weekdays vs. weekends), your customers can use AWS EventBridge to trigger Lambda functions that update the IAM trust policy or set the `DeployAccess` tag based on their schedule.
Similar automation can be built in other environments using Google Cloud IAM conditions or Azure Conditional Access policies.
### Release windows
Your customers control when deployments are allowed by combining their cloud provider's access control features with their own automation:
* **Time-based conditions**: Use condition keys (like `aws:CurrentTime` in AWS) in IAM policies to restrict deployments to specific time ranges
* **Tag-based gating**: Control approval tags programmatically via scheduled automation or manual approval workflows
* **Always require manual approval**: Omit time-based conditions entirely and rely on manual tag updates
This approach provides flexibility while keeping access control entirely within customer-managed policies.
## Permissions across form factors
Permission models vary by form factor:
| Form Factor | Identity Mechanism | Conditional Access | Audit Logging | Access Management |
| ---------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | ----------------------------------------------------- |
| **AWS** | IAM roles for all permission phases | Conditional assume role for deploy and install permissions | CloudTrail logging for full auditability | Integration with AWS SSO for operator access |
| **Google Cloud** | Service accounts for all permission phases | IAM conditions on service account impersonation | Cloud Audit Logs for full auditability | Integration with Google Workspace for operator access |
| **Azure** | Managed identities for all permission phases | Conditional access policies for deploy and install permissions | Azure Monitor logging for full auditability | Integration with Azure AD for operator access |
| **Private Kubernetes** | Kubernetes service accounts for all permission phases | RBAC roles and role bindings define permissions. Customer-defined approval mechanisms (custom operators, external approval systems) | Audit logging to customer SIEM | Customer-controlled access management |
| **Digital Ocean** | API tokens with scoped permissions | Time-bounded tokens for deploy and install permissions | Audit logs available through API | Integration with customer access management systems |
## Audit logging
All permission assumptions and operations are logged:
### What gets logged
| Event Type | What Gets Logged |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Role assumptions** | When steady-state assumes deploy or install roles, including timestamps, requesting identity, and approval status |
| **Operations commands** | Every kubectl, database query, or other operation executed on the appliance |
| **Deployments** | Terraform/CloudFormation executions, including what resources were created, updated, or deleted |
| **Permission denials** | Failed assumption attempts or unauthorized operations, including the reason for denial |
### Where logs are stored
| Type | Log System | What It Contains |
| ---------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Appliance audit logs** | CloudTrail (AWS), Cloud Audit Logs (GCP), Azure Monitor (Azure), Kubernetes Audit Logs to SIEM (private) | All API calls, role assumptions, resource modifications, and operations within the customer's appliance. Stored in customer-controlled infrastructure. |
| **Control plane audit logs** | Vendor-maintained audit trail | All operations initiated by the vendor control plane, deployment history, approval workflows, and permission requests. Stored in vendor infrastructure. |
Customers have complete visibility into what your control plane does within their infrastructure.
## Best practices
Design your application to operate with steady-state permissions whenever possible. Minimize the frequency of deployments requiring deploy permissions.
When requesting deploy access, include clear descriptions of what the deployment does and why elevated permissions are needed. This helps customers make informed approval decisions.
Honor customer-defined release windows. Don't request deploy access outside approved time windows unless it's a genuine emergency.
After initial appliance setup, avoid operations requiring install permissions. Use deploy permissions for routine updates and only request install permissions for major architectural changes.
Maintain your own audit trail of what operations your team performs on customer appliances. This helps with customer support and incident investigation.
Clearly document what permissions your application requires for each phase. This helps customers understand and approve your permission model.
## Related topics
* [**Appliances**](/fundamentals/appliances): Understanding customer appliances
* [**Deployments**](/fundamentals/deployments): How deployments use deploy permissions
* [**Operations**](/fundamentals/operations): Remote operations on appliances
* [**Observability**](/fundamentals/observability): How observability uses steady-state permissions