Skip to content

Install the agent

Create a node bot, then install the agent on an EZGH instance or any other Linux machine so it registers as a node.

Updated View as Markdown

The agent runs as root under systemd, connects out to EZGH and registers the machine as a node in a project. It acts as a bot, the node bot: the bot’s key is all it needs to register.

Create a node bot

A node bot needs only two actions: fleets.nodes.register on the project and fleets.nodes.connect on its nodes. The managed policy FleetsManagedNodeAccess has both.

Use one node bot per group of machines (web servers, build machines), so that revoking one group doesn’t touch the others.

  1. Open Fleets > Nodes and choose Set up a node Bot.
  2. Name the bot and create it. The console attaches FleetsManagedNodeAccess to it and shows the install commands for it.
ezgh iam bots create web-nodes
ezgh iam policies attach FleetsManagedNodeAccess --bot web-nodes

FleetsManagedNodeAccess lets the bot register machines in any project of the organization. To keep it to one project, give the bot a policy of your own instead:

{
  "statements": [
    {
      "effect": "allow",
      "actions": ["organizations.get", "fleets.nodes.register", "fleets.nodes.connect"],
      "resources": [
        "ezgh:*:org_k3f9a0x2m7qp",
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2",
        "ezgh:*:org_k3f9a0x2m7qp:prj_g7h8i9j0k1l2:nod_*"
      ]
    }
  ]
}

Project and organization IDs

The agent names the project, and the organization where it’s needed, by its ID: a UUID such as 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7, not its prj_… or org_… name. The console’s install commands fill it in, and ezgh projects get and ezgh orgs get show it.

On an EZGH instance

The agent gets short-lived keys for the instance’s bot from the metadata service, so there’s no key to store.

  1. Attach the node bot to the instance (the instance’s Bot, or ezgh compute instances update web-1 --bot bot_a1b2c3d4e5f6).

  2. On the instance, run:

    curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7

The node is linked to the instance and named after it, and it has the instance’s tags, kept up to date each time the agent connects. If the instance has no bot yet, the agent waits and checks again every few minutes, so attaching the bot later is enough.

On another Linux machine

  1. Create an API key for the node bot, and save it on the machine as node-bot.key (chmod 600 node-bot.key).

  2. Run:

    curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- \
      --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7 --api-key-file node-bot.key

    The script copies the key to /etc/ezgh-fleets-agent/credentials, readable only by root.

  3. Delete node-bot.key.

Where the machine has a workload identity, such as a Kubernetes service account token, the agent exchanges it for short-lived keys instead, and no key is stored. Set up the bot’s OIDC trust first, then run:

curl -fsSL https://get.ezghcloud.com/fleets/install.sh | sudo sh -s -- \
  --project 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7 --organization 4d5e6f70-8192-4a3b-9c4d-5e6f708192a3 \
  --oidc-bot bot_a1b2c3d4e5f6 --oidc-token-file /var/run/secrets/ezgh/token

A node outside EZGH has no tags until you add them: in the console on the node’s page, or in UpdateNode. The agent never sets a node’s tags, so a machine can’t tag itself into a run.

What the install script does

The script adds the signed EZGH package repository for apt or yum, installs the ezgh-fleets-agent package, writes /etc/ezgh-fleets-agent/config.yaml and starts the service. It does nothing the package can’t do, and it’s short enough to read before you run it. You can also add the repository and install the package yourself: .deb, .rpm and a static tarball are published for amd64 and arm64. The agent updates with the rest of the machine’s packages.

# /etc/ezgh-fleets-agent/config.yaml
project: 9f3c2a1e-6b7d-4e8f-a0b1-c2d3e4f5a6b7      # required: the project's ID
organization: 4d5e6f70-8192-4a3b-9c4d-5e6f708192a3 # optional: learned from the bot's key
credentials:
  source: auto   # auto | metadata | file | oidc
  file: /etc/ezgh-fleets-agent/credentials
  oidc: { bot: bot_a1b2c3d4e5f6, tokenFile: /var/run/secrets/ezgh/token }

auto uses the metadata service on an EZGH instance, and the key file elsewhere.

The node’s binding

When the agent first registers, it makes a key pair of its own and keeps the private half in /var/lib/ezgh-fleets-agent, readable only by root. It signs every connection with it. So a copied bot key can register a new node, but it can’t take over an existing one.

  • An instance has one node. Registering again from an instance that already has one fails. If you reinstall the agent or rebuild the disk, choose Reset on the node’s page (or ezgh fleets nodes reset web-1). Reset ends the node’s sessions and shows it as Awaiting registration, and the next registration from the instance keeps the node’s ID. Check the agent version and the time it registered afterwards.
  • Another machine registers a new node each time its state directory is lost. Deregister the old one. Resetting a node on another machine works the same way: its agent registers again as a new node, with a new ID and no tags, and the reset node stays Awaiting registration until you deregister it.

Disconnect a machine

Removing the bot’s permission, deleting the bot or revoking its key disconnects its nodes within 10 minutes. To remove a node, choose Deregister on its page or run ezgh fleets nodes deregister web-1, then uninstall the package from the machine.

Limits

A project can have 1,000 nodes, online or not (adjustable in Service quotas).

Navigation

Type to search…

↑↓ navigate↵ selectEsc close