Google GCE

In Juju, Google GCE is a machine cloud and works as described below.

Note

This reference assumes basic familiarity with Juju. If you are new to Juju, start with the Tutorial, then use this page together with the generic materials it links to and/or consult the example workflows.

Requirements

Juju needs Service Account Key Admin, Compute Instance Admin, and Compute Security Admin to create and manage the GCE resources used during cloud registration and bootstrap.

See more: Google | Compute Engine IAM roles and permissions

Concepts

The following table shows how GCE abstractions map to Juju concepts:

GCE

Juju

Project

Administrative boundary for models (roughly)

Compute Engine instance

machine

Process on a VM

unit

Managed set of workload instances

application

Persistent Disk

storage

VPC/subnet

Network spaces and placement targets (roughly)

The cloud

See also: Cloud, Juju | Manage clouds, Terraform Provider for Juju | Manage clouds

As for all machine clouds, the cloud is registered in Juju via a cloud definition, stored in clouds.yaml on the client (on Linux: ~/.local/share/juju/clouds.yaml) and following this schema:

clouds:
  <cloud-name>:  # Predefined name
    type: gce
    auth-types:
      - <auth-type>                # See Authentication types below
    regions:
      <region-name>:               # e.g. us-central1
        endpoint: <endpoint>       # Region-specific GCE API endpoint
    config:                        # Optional: model config defaults
      <config-key>: <value>        # See Configuration keys below

Credentials

See also: Credential, Juju | Manage credentials, Terraform Provider for Juju | Manage credentials

As for all machine clouds, credentials are stored in credentials.yaml on the client and follow this schema:

credentials:
  google                         # Predefined cloud name for GCE
    <credential-name>:             # User-defined credential name
      auth-type: <auth-type>       # oauth2 | jsonfile | service-account (see Authentication types below)
      <attribute>: <value>         # Auth-type-specific attributes (see below)

Authentication types

Google GCE supports the following authentication types:

oauth2

Attributes:

  • client-id: Client ID (required).

  • client-email: Client e-mail address (required).

  • private-key: Client secret (required).

  • project-id: Project ID (required).

jsonfile

Attributes:

  • file: Path to the .json file containing a service account key for your project (required).

Auto-detection: If GOOGLE_APPLICATION_CREDENTIALS is set to a valid file path, juju autoload-credentials detects this credential type automatically. If CLOUDSDK_COMPUTE_REGION is also set, it becomes the default region for the detected credential.

See more: Authenticate with a credential and a service account

service-account

Requirements:

  • Juju 3.6+

  • A service account with sufficient privileges:

    • https://www.googleapis.com/auth/compute

    • https://www.googleapis.com/auth/devstorage.full_control

  • The add-credential steps must be run from a jump host running in Google Cloud to reach the cloud metadata endpoint.

See more: Authenticate with a service account (recommended)

Controllers

See also: Controller, Juju | Manage controllers, Terraform Provider for Juju | Manage controllers

Bootstrap behavior

Creates a controller instance on GCE in a single API request. Juju creates the required GCE resources directly – no templates.

Resources created at bootstrap

The controller runs on a GCE instance provisioned using the same mechanisms as workload machines – see Resources created per machine for the full per-machine resource model. Controller-specific differences are noted below.

Compute

  • Compute instance: Ubuntu LTS instance. Machine type selected based on hardware constraints (default n1-standard-1). Instance creation includes boot disk inline.

  • Service account (optional): Attached if credential type is service-account or instance-role constraint specified. Scopes: compute, devstorage.full_control. Enables metadata service credentials.

  • Instance metadata: Tagged with juju-controller-uuid, juju-is-controller: true, and bootstrap metadata.

  • Instance tags: juju-<model-uuid> (for firewall targeting), hostname.

Networking

  • Network interface: Primary interface in specified VPC/subnet or default network. Private IP auto-assigned from subnet CIDR. External NAT with public IP if allocate-public-ip=true (default).

  • Firewall rule: Global VPC firewall rule juju-<model-uuid> targeting instances tagged juju-<model-uuid>. Created with no initial rules; rules are added dynamically via open-ports.

Storage

  • Boot disk: Persistent disk, device name auto-assigned. Default 10 GiB minimum (expanded if constraint/image requires). Type pd-standard (default) or pd-ssd. Auto-deleted when instance terminates.

Models

See also: Model, Juju | Manage models, Terraform Provider for Juju | Manage models

Configuration keys

Google GCE supports the following cloud-specific model configuration keys:

Networking

  • vpc-id: Use a specific VPC network. When not specified, Juju requires a default VPC to be available for the account. Example: vpc-a1b2c3d4. Type: string. Default: "". Immutable.

  • vpc-id-force: Force Juju to use the GCE VPC ID specified with vpc-id, when it fails the minimum validation criteria. Type: bool. Default: false. Immutable.

Storage

  • base-image-path: Base path to look for machine disk images. Type: string. Default: none.

Machines

See also: Machine, Juju | Manage machines, Terraform Provider for Juju | Manage machines

Constraints

Google GCE supports the following constraints:

Note

The constraints instance-type and [arch, cores, cpu-power, mem] are mutually exclusive.

Compute

Networking

Storage

Placement directives

Google GCE supports the following placement directives:

Resources created per machine

Applies to all machines, including controller machines. Controller-specific defaults are documented in Resources created at bootstrap.

Compute

  • Compute instance: Instance with name <model-uuid><machine-id>. Machine type selected based on constraints. Status sequence: PROVISIONING → STAGING → RUNNING.

  • Service account (optional): Attached if instance-role constraint specified. Enables metadata service credentials.

  • Instance metadata: Bootstrap metadata, controller UUID, and model UUID.

  • Instance tags: juju-<model-uuid>, hostname (for firewall targeting).

Networking

  • Network interface: Primary interface in VPC/subnet. Private IP auto-assigned. External NAT with public IP if allocate-public-ip=true.

Storage

  • Boot disk: Persistent disk attached inline. Size: max(10 GiB, constraint, image minimum). Type: pd-standard (default) or pd-ssd via root-disk-source constraint. Auto-deleted when instance terminates.

  • Additional persistent disks (optional): Created when storage specified via storage constraints. Must reside in same zone as instance.

  • Disk labels: juju-model, juju-controller (set via upgrade step).

Networking behavior

  • VPC requirements: If you use a VPC, Juju validates the configuration before bootstrap. A valid VPC must have: at least one subnet with status READY, OR AutoCreateSubnetworks=true enabled; SSH access enabled (firewall rule for port 22).

  • VPC/subnet selection: Uses VPC configured via vpc-id model config or default network (global/networks/default). Subnet selection driven by zone or subnet placement directives. Random selection from available subnets in region. Space constraints filter to valid subnets.

  • Public IP handling: Assigned via external NAT (ONE_TO_ONE_NAT) if allocate-public-ip=true (default). Ephemeral public IP auto-assigned by GCE.

  • Firewall rules: Environment-level rule (juju-<model-uuid>) allows traffic between instances with same tag. Per-machine rules target instance by hostname tag. User-defined port rules via open-ports create additional firewall rules.

  • Address resolution: Returns private address (cloud-local scope, from subnet CIDR) and public address (if NAT configured).

Storage behavior

See also: gce for the GCE storage provider configuration options.

  • Boot disk: Persistent disk, type pd-standard by default. Configurable via root-disk-source constraint (specify a storage pool with disk-type).

  • Additional disks: Must reside in the same availability zone as the instance.

  • Auto-deletion: Boot disks are auto-deleted when the instance terminates.

Storage

See also: Storage, Juju | Manage storage

Storage providers

In addition to generic storage providers, Google GCE provides the following cloud-specific storage providers:

gce

Type: GCE persistent disks

Configuration options:

  • disk-type: Disk type. Valid values: pd-standard (default), pd-ssd.

Appendix: Example workflows

Authenticate with a credential and a service account

Requirements:

  • Juju 3.6+

  • A service account with sufficient privileges (see service-account authentication type above).

Steps:

  1. Bootstrap with the arg --bootstrap-constraints="instance-role=<your-service-account-email>".

  2. The controller machines will be created and attached to that service account.

  3. To use the project’s default service account, set instance-role=auto instead.

Tip

To configure workload machines to use a different (less privileged) service account, use the instance-role constraint. This can be set on the model to apply to all (non-controller) machines.