CLI IAM

CLI: IAM

The guards documented below stop mistakes, not a caller that already holds IAM write rights: give agent profiles an IAM user without IAM write rights, and turn on read_only where they only read, so the server itself refuses what a guard would. A caller whose own type is a service account is refused on every write that targets an existing service account (update-service-account, delete-service-account, and reset-service-account-secret), since its own identity cannot be confirmed against a target's ID or ClientID.

add-user-to-group

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the user is the caller or the group is one the caller already belongs to, and PrivilegedChange when the user or the group otherwise holds a privileged policy; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--group-id	string	yes
--user-id	string	yes

vngcloud iam add-user-to-group --group-id <group-id> --user-id <user-id> --yes

attach-group-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the group is one the caller already belongs to, and PrivilegedChange when the policy grants an IAM write action or the group otherwise holds one; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--group-id	string	yes

vngcloud iam attach-group-policy --policy-id <policy-id> --group-id <group-id> --yes

attach-service-account-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the caller's own type is a service account, and PrivilegedChange when the policy grants an IAM write action or the target service account already holds one; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--service-account-id	string	yes

vngcloud iam attach-service-account-policy --policy-id <policy-id> --service-account-id <service-account-id> --yes

attach-user-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the user is the caller, and PrivilegedChange when the policy grants an IAM write action or the user otherwise holds one, directly or through a group; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--user-id	string	yes

vngcloud iam attach-user-policy --policy-id <policy-id> --user-id <user-id> --yes

create-group

Kind: Write.

Changes no one's rights and has no guard beyond read-only: a new group starts with no members and no attached policy, added only through add-user-to-group and attach-group-policy. Never retried after a failure that may have already reached the server: list groups by --name before creating it again rather than repeating this command.

Flag	Type	Required
--name	string	yes
--description	string

vngcloud iam create-group --name <name>

create-policy

Kind: Write.

Refuses, before any request, with error code PrivilegedChange when the statements grant an IAM write action; see the IAM design's guard rules. Never retried after a failure that may have already reached the server: list policies by --name before creating it again rather than repeating this command.

Statements has no flag of its own; set it with --document-file , a JSON object in the console's own form, or --cli-input-json (Statements, its exact Go field name). --document-file wins when both are given. The file must be a regular file of at most 64 KiB, opened without following a FIFO or other special file, and is decoded with unknown fields refused: an AWS-style document (top-level Version and Statement, or a statement's own Action and Resource) exits 2 before any request instead of reaching the server as an empty policy. Keys match without regard to case, so get-policy's own Go field names (Statements, Effect, Actions, Resources) decode the same way as the console's lower-case ones. Example, granting a read-only vServer action:

{"statements": [{"effect": "allow", "actions": ["vserver:ListServers"], "resources": ["*"]}]}

Flag	Type	Required
--name	string	yes
--description	string
Statements (via --cli-input-json only)	[]iam.Statement	yes
--document-file	string

vngcloud iam create-policy --name <name> --document-file policy.json

create-service-account

Kind: Write.

Needs --secret-file : the client secret is returned once, and this command writes it only to that file, at mode 0600, never to stdout, stderr, --debug, or an error message; the printed ClientSecret field always reads "[redacted]", and a SecretFile field names the path. --secret-file must not already exist, symlink included, checked before any request. If the create response holds no client secret at all, the new service account is kept, no file is written, and the command exits 1 with error code SecretFileFailed naming reset-service-account-secret. If the read the SDK makes after the create to confirm the new account fails, --secret-file is still written from the create response's own secret and the account is kept, but the command exits 1 naming list-service-accounts, since the account's other fields could not be confirmed. If writing --secret-file itself fails after a secret was returned, the new service account is deleted through the SDK and the command exits 1 with SecretFileFailed; if that delete also fails, the message names the service account only by its ID. Never retried after a failure that may have already reached the server: list service accounts by --name before creating it again rather than repeating this command; a service account found that way has already lost its client secret and needs reset-service-account-secret. A failed confirm read preserves the ID and secret but may omit ClientID: recover it with get-service-account --service-account-id , never another create. Configure a fresh profile using client_id and stdin-only client_secret, then set read_only last; see Configuration.

Flag	Type	Required
--name	string	yes
--description	string
--secret-file	string	yes

vngcloud iam create-service-account --name <name> --secret-file <secret-file>

delete-group

Kind: Write, destructive.

Refuses, before any request, with error code ResourceInUse when the group has a member or an attached policy, protected or not: removing it would silently take rights from whatever it is attached to. See the IAM design's guard rules.

Flag	Type	Required
--group-id	string	yes

vngcloud iam delete-group --group-id <group-id> --yes

delete-policy

Kind: Write, destructive.

Refuses, before any request, with error code ManagedPolicy when the policy is managed, and ResourceInUse when it is attached to a group, an IAM user, or a service account; see the IAM design's guard rules.

Flag	Type	Required
--policy-id	string	yes

vngcloud iam delete-policy --policy-id <policy-id> --yes

delete-service-account

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the service account is the caller's own token, or the caller's own type is a service account (every service account target is refused then, not only the caller's own ID), and PrivilegedChange when the target holds a policy that grants an IAM write right; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--service-account-id	string	yes

vngcloud iam delete-service-account --service-account-id <service-account-id> --yes

detach-group-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the group is one the caller already belongs to, and PrivilegedChange when the policy grants an IAM write action or the group otherwise holds one; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--group-id	string	yes

vngcloud iam detach-group-policy --policy-id <policy-id> --group-id <group-id> --yes

detach-service-account-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the caller's own type is a service account, and PrivilegedChange when the policy grants an IAM write action or the target service account already holds one; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--service-account-id	string	yes

vngcloud iam detach-service-account-policy --policy-id <policy-id> --service-account-id <service-account-id> --yes

detach-user-policy

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the user is the caller, and PrivilegedChange when the policy grants an IAM write action or the user otherwise holds one, directly or through a group; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--policy-id	string	yes
--user-id	string	yes

vngcloud iam detach-user-policy --policy-id <policy-id> --user-id <user-id> --yes

get-caller-identity

Kind: Read.

No fields.

vngcloud iam get-caller-identity

get-group

Kind: Read.

Flag	Type	Required
--group-id	string	yes

vngcloud iam get-group --group-id <group-id> --query Group

get-policy

Kind: Read.

Flag	Type	Required
--policy-id	string	yes

vngcloud iam get-policy --policy-id <policy-id> --query Policy

get-service-account

Kind: Read.

Flag	Type	Required
--service-account-id	string	yes

vngcloud iam get-service-account --service-account-id <service-account-id> --query ServiceAccount

list-actions

Kind: Read.

No fields.

vngcloud iam list-actions

list-group-policies

Kind: Read.

Flag	Type	Required
--group-id	string	yes
--page	int
--size	int

vngcloud iam list-group-policies --group-id <group-id>

list-groups

Kind: Read.

No fields.

vngcloud iam list-groups

list-policies

Kind: Read.

Flag	Type	Required
--name	string
--page	int
--size	int

vngcloud iam list-policies

list-policy-attachments

Kind: Read.

Flag	Type	Required
--policy-id	string	yes

vngcloud iam list-policy-attachments --policy-id <policy-id>

list-service-account-policies

Kind: Read.

Flag	Type	Required
--service-account-id	string	yes
--page	int
--size	int

vngcloud iam list-service-account-policies --service-account-id <service-account-id>

list-service-accounts

Kind: Read.

Flag	Type	Required
--name	string
--page	int
--size	int

vngcloud iam list-service-accounts

list-user-groups

Kind: Read.

Flag	Type	Required
--user-id	string	yes

vngcloud iam list-user-groups --user-id <user-id>

list-user-policies

Kind: Read.

Flag	Type	Required
--user-id	string	yes
--page	int
--size	int

vngcloud iam list-user-policies --user-id <user-id>

list-users

Kind: Read.

Flag	Type	Required
--page	int
--size	int

vngcloud iam list-users

remove-user-from-group

Kind: Write, destructive.

Refuses, before any request, with error code SelfChange when the user is the caller or the group is one the caller already belongs to, and PrivilegedChange when the user or the group otherwise holds a privileged policy; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--group-id	string	yes
--user-id	string	yes

vngcloud iam remove-user-from-group --group-id <group-id> --user-id <user-id> --yes

reset-service-account-secret

Kind: Write, destructive.

Needs --secret-file , checked the same way as create-service-account: must not already exist, symlink included, checked before any request. The previous secret stops working for new exchanges when the reset request lands; if the response then holds no client secret at all, or if writing --secret-file fails, there is no way to get it back, so the command exits 1 with error code SecretFileFailed naming the service account and telling the caller to run reset-service-account-secret again, rather than deleting anything. Never retried after a failure that may have already reached the server: no read shows whether the secret changed, so treat the previous secret as replaced. Replace the protected credentials, rebuild configs, and restart consumers. Old issued tokens and cache entries may survive; reset does not promise immediate token revocation or automatic cache purging. A read_only profile needs a trusted editor or provisioner for rotation.

Refuses, before any request, with error code SelfChange when the service account is the caller's own token, or the caller's own type is a service account (every service account target is refused then, not only the caller's own ID), and PrivilegedChange when the target holds a policy that grants an IAM write right; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--service-account-id	string	yes
--secret-file	string	yes

vngcloud iam reset-service-account-secret --service-account-id <service-account-id> --secret-file <secret-file> --yes

update-group

Kind: Write.

Changes no one's rights and has no guard beyond read-only. Sends a full PATCH, reading the group first to fill Name when left unset, since the request requires a name either way; Description is sent only when set, and left as is otherwise.

Flag	Type	Required
--group-id	string	yes
--name	*string
--description	*string

vngcloud iam update-group --group-id <group-id>

update-policy

Kind: Write, destructive.

Refuses, before any request, with error code ManagedPolicy when the policy is managed, and PrivilegedChange when its current or proposed statements grant an IAM write action, or it is attached to a protected principal or group; see the IAM design's guard rules. Sends a full PUT, filling any field left unset (Name, Description, Statements) from the policy's own current state first, so leaving out --document-file keeps the current statements rather than clearing them.

Statements has no flag of its own; set it with --document-file , a JSON object in the console's own form, or --cli-input-json (Statements, its exact Go field name). --document-file wins when both are given. The file must be a regular file of at most 64 KiB, opened without following a FIFO or other special file, and is decoded with unknown fields refused: an AWS-style document (top-level Version and Statement, or a statement's own Action and Resource) exits 2 before any request instead of reaching the server as an empty policy. Keys match without regard to case, so get-policy's own Go field names (Statements, Effect, Actions, Resources) decode the same way as the console's lower-case ones. Example, granting a read-only vServer action:

{"statements": [{"effect": "allow", "actions": ["vserver:ListServers"], "resources": ["*"]}]}

Flag	Type	Required
--policy-id	string	yes
--name	*string
--description	*string
Statements (via --cli-input-json only)	*[]iam.Statement
--document-file	string

vngcloud iam update-policy --policy-id <policy-id> --document-file policy.json --yes

update-service-account

Kind: Write.

Refuses, before any request, with error code SelfChange when the service account is the caller's own token, or the caller's own type is a service account (every service account target is refused then, not only the caller's own ID), and PrivilegedChange when the target holds a policy that grants an IAM write right; see the IAM design's guard rules. Neither guard has a flag or Input field that turns it off.

Flag	Type	Required
--service-account-id	string	yes
--description	*string
--access-token-life-span	*int

vngcloud iam update-service-account --service-account-id <service-account-id>