GreenNode

Connect GreenNode so agents can read vServer, VKS, vLB, vDB, and storage resources and run changes through the GreenNode CLI under your Approvals

Connect GreenNode to let CloudThinker agents read and operate your GreenNode resources, such as vServer instances, VKS clusters, load balancers, databases, and storage. The connection signs in with a service account (a client ID and client secret) and runs the official GreenNode CLI, grn, in one region.

Prerequisites

• Access to GreenNode IAM with permission to create a service account.
• The GreenNode region that holds your resources: HCM-3 (Ho Chi Minh City) or HAN (Hanoi).
• For vServer work, the Project ID of the project you want agents to use, and your numeric Account ID. GreenNode does not pick a project for you.
• The Admin role in your CloudThinker workspace, which can add and edit connections. See Roles.

A workspace holds one GreenNode connection, for one region and one project. To cover both HCM-3 and HAN, or a second project, create a separate workspace for each, with its own members and Approvals settings.

Copy the Client secret as soon as you create the service account, and store it somewhere safe. If you lose it, you create a new service account and swap in its values with Rotate a credential.

Setup

1. Create a GreenNode service account

   Open GreenNode IAM → Service accounts, then:

   1. Click Create a Service account.
   2. Enter a name, such as cloudthinker.
   3. In the scope picker, select only the scopes for the services you want agents to use. See Required permissions.
   4. Click Create Service account.
   5. Copy the Client ID and Client secret.
2. vServer only: copy your Project ID and Account ID

   Skip this step if agents won’t work with vServer.

   1. In the GreenNode dashboard, open vServer → Limit and copy User Project ID for the project you want agents to use.
   2. Click your avatar in the upper-right corner and hover over the Currently signed in as card. Copy the numeric Account ID, such as 123456. Do not use the account email. The CloudThinker form calls this value Portal user ID.
3. Add the connection in CloudThinker

   Open More → Workspace settings → Connections, select GreenNode, and fill in the fields from Connection details. For vServer, enter the User Project ID in Project ID and the Account ID in Portal user ID. Otherwise leave both blank. Click Connect.

   Success state: the connection shows Connecting and Verifying, then a Connected status. CloudThinker verifies the credentials by reading the service account’s identity from GreenNode IAM.

   If the test fails, the connection shows Error with Retry (test the saved values again) and Replace credentials (enter new ones). To change values on a working connection, follow Rotate a credential.

Connection details

The form has these five fields and no others.

Field	Required	What to enter
Client ID	Yes	The service account’s client ID.
Client secret	Yes	The service account’s client secret.
Portal user ID	For vServer	Your numeric GreenNode Account ID (same value, different label). Must be a positive whole number. Leave blank if you don’t use vServer.
Default region	Yes	HCM-3 (preselected) or HAN. Despite the label, this is the only region the connection covers, so agents can’t reach the other one. To cover both, use a second workspace.
Project ID	For vServer	The project agents work in. vServer commands fail without it. VKS doesn’t use it.

Required permissions

The service account’s scopes decide everything agents can see and change. CloudThinker adds no access of its own.

• Required for the connection test: the scope that lets the service account read its own IAM identity. CloudThinker runs grn iam whoami to test the connection, and it fails without that scope.
• For each service you want agents to inspect, grant its read scopes only.
• Add write scopes for a service only when you want agents to change it, for example starting or stopping vServer instances.

Start with read scopes for the one or two services you care about, such as vServer and VKS. If an agent reports a permission error, add the scope GreenNode names and test again.

Agent capabilities

Agents use the GreenNode CLI and read its built-in help before each command, so they only run operations the CLI actually offers. The CLI covers 13 service groups:

Service group	What agents can work with
vserver	Virtual servers and their volumes
vks	VKS Kubernetes clusters
vlb	Load balancers
vdb	Managed databases
vstorage, vstorage-gateway	Storage and storage gateways
vbackup	Backups
vcr	Container registry
vmonitor, vmonitor-log	Metrics and logs
iam	Identity and access
saas-ai, agentbase	GreenNode AI platform services

Reads run without asking. Allow writes on the connection’s detail panel is on by default; turn it off to refuse every change. Any create, update, delete, start, stop, resize, attach, restore, or other change goes through Approvals first.

Every change an agent makes goes through your workspace’s Approvals first. On the default Auto · Rules + AI · Ask me mode, AI judgment can let a safe change run without asking — and an Allow Rule can too, once CloudThinker turns on Rule enforcement for your workspace. Choose Manual to approve every change yourself.

If the CLI has no command for what you ask, the agent tells you instead of working around it, and names the closest actions the CLI does offer.

Verify the connection

Who am I signed in as on GreenNode, and which VKS clusters exist in my region?

Expect the service account identity, then a list of VKS clusters, or a clear statement that the region has none.

Example prompts

List my GreenNode vServer instances with their status and flavor
List my VKS clusters with their status and Kubernetes version
Stop the vServer instance web-01, and show me the exact change before you run it

Troubleshooting

GreenNode requires GRN_ACCESS_KEY_ID and GRN_SECRET_ACCESS_KEY

GRN_ACCESS_KEY_ID is the Client ID field and GRN_SECRET_ACCESS_KEY is the Client secret field. One of them is empty. Enter both values from the service account, then test again.

GreenNode region must be HCM-3 or HAN

Select HCM-3 or HAN in Default region, then test again.

GreenNode portal user ID must be a positive numeric value

Portal user ID holds an email or other text. Enter the numeric Account ID from the Currently signed in as card, or clear the field.

GreenNode project ID contains unsupported characters

Project ID has a space or a character GreenNode does not use. Copy User Project ID again from vServer → Limit, without extra characters.

GreenNode rejected the credentials or they lack the required read permission

The client ID or secret is wrong, the service account was deleted, or it cannot read its own IAM identity. Check the service account in GreenNode IAM. To enter new values, click Replace credentials on the errored connection, or follow Rotate a credential.

GreenNode did not answer before the connection test timeout

GreenNode didn’t answer within the test window, which is 60 seconds. Wait a few minutes, then test the connection again.

Connection 'greennode' already exists. Only one instance is allowed.

This workspace already has a GreenNode connection. Edit that connection, or disconnect it first.

vServer questions fail but VKS works

vServer commands need Project ID, and some also need Portal user ID. Add both, then test again.

Security

• Least privilege — grant only the permissions the agents need for your use case; start read-only and widen later.
• Read-only by default — use read-only credentials unless you want agents to make changes through this connection.
• Rotate credentials — rotate keys and tokens on your normal schedule; CloudThinker picks up the new value when you update the connection.
• Revoke on offboarding — remove the credential at the provider when you delete a connection or a teammate leaves.

• Credentials stay out of commands: CloudThinker passes the client ID and secret to the CLI as environment values, and agents cannot print them, override the GreenNode endpoint, or turn off certificate checks.
• Rotate the secret: to swap in a new client ID and secret, follow Rotate a credential.
• Revoke at the source: delete the service account in GreenNode IAM to stop all access through this connection at once.

Related

Connections

See every service you can connect and how connection status works.

Approvals

Decide which GreenNode changes run, wait for a person, or are refused.