Skip to content
Kyku

Role

A Role defines a set of permissions that can be assigned to Identity resources. Permissions use an abstract format (resource:action) that maps to provider-native equivalents. On AWS this is an IAM Role with policy documents, on GCP a Custom Role.

Config

Section titled “Config”
Property Type Required Description
name string yes Unique resource name
id string no Explicit ID (auto-generated UUID if omitted)
provider string no Provider label for multi-provider configs
tags Record<string, string> no Arbitrary key-value metadata
permissions Permission[] yes List of abstract permissions

Permission values

Section titled “Permission values”
Permission Description
compute:read List/describe compute resources
compute:write Create/update/delete compute resources
compute:admin Full compute access
network:read List/describe network resources
network:write Create/update/delete network resources
network:admin Full network access
storage:read List/read storage resources
storage:write Create/update/delete storage resources
storage:admin Full storage access
database:connect Connect to databases
database:read Read database metadata
database:write Modify database resources
database:admin Full database access
iam:read List/describe IAM resources
iam:write Create/update/delete IAM resources
iam:admin Full IAM access
string Provider-specific permission (e.g. ec2:DescribeInstances)

Example

Section titled “Example”
import { Role } from '@kykucloud/types'


const readonlyRole = new Role({
  name: 'readonly',
  permissions: ['compute:read', 'storage:read', 'database:read'],
})


const customRole = new Role({
  name: 'custom',
  permissions: ['compute:read', 's3:GetObject', 's3:ListBucket'],
})

Provider Support

Section titled “Provider Support”
Provider Supported Backend
AWS ✅ IAM Role (with managed/inline policy)
GCP ✅ Custom Role (IAM API)
Hetzner ❌ Not available
DigitalOcean ❌ Not available

Notes

Section titled “Notes”
  • AWS IAM roles require policy cleanup before deletion — destroy() must detach managed policies and delete inline policies. AWS role names are immutable (rename is a separate operation).
  • GCP Custom Roles are created via POST /v1/projects/{project}/roles using the IAM API base (iam.googleapis.com).
  • Abstract permissions like compute:read map to provider-specific actions (AWS: ec2:Describe*, GCP: compute.instances.list).
  • Provider-specific string permissions bypass the abstract mapping and are passed directly to the provider. Use when the abstract permissions are insufficient.