Configure the appliance and install software

This page describes how to set up and configure Google Distributed Cloud (GDC) air-gapped appliance at the customer site.

On first boot, the drives are unlocked without human intervention.

Important: To access the URLs on this page, you must connect to the internet. The URLs are provided for use when you have such access.

Decrypt the drive and boot the machine

For each GDC air-gapped appliance, three or more Yubikeys are shipped separately to the customer. For more information on the Yubikey model, see https://www.yubico.com/product/yubikey-5-nano-fips/.

To decrypt the drive and boot the machine, insert one Yubikey into each server machine. The CLI registers the Yubikey by performing the following steps:

1. The CLI uses cryptsetup to enroll the Yubikey as the LUKS (Linux Unified Key Setup) key store for the unlock key.
2. After a Yubikey is enrolled, the CLI disables initramfs-based unlocking. When this step completes, you must use only the Yubikey of the corresponding server machine to unlock the drive.

Configure the appliance

1. Run the following command on the laptop to configure the appliance.

      gdcloud appliance configure
   

2. When prompted, answer a series of questions and enter your responses in each of the following sections.

Domain Name System (DNS) information

1. Enter the DNS delegated subdomain name for the GDC air-gapped appliance instance from the parent DNS server. This fully qualified domain name is used as a suffix for GDC air-gapped appliance services such as admin cluster management. The expected format is LOCATION.SUFFIX.

   Replace the following:

   • LOCATION: the zone identifier of the GDC air-gapped appliance deployment, such as us-central1-a
   • SUFFIX: any valid DNS suffix, such as zone1.google.gdch.test or us-central1-a.gdch.customer

2. Enter a comma-delimited list of IP addresses that represent the nameservers in your network used for address resolution. These DNS servers provide GDC air-gapped appliance with access to external customer services. For example, 8.8.8.8,8.8.4.4.

Border Gateway Protocol (BGP) information

Border Gateway Protocol (BGP) exchanges routing information with external networks. These networks are identified using autonomous system numbers (ASN). To ensure proper connectivity between GDC air-gapped appliance and the external networks, all ASN values must be globally unique.

1. Enter the ASN assigned to the data plane for the GDC air-gapped appliance instance. For example 65204.
2. Enter the ASN assigned to the data plane for the customer network. For example, 4200002002.

Data plane network

1. For the data plane IP family network, specify if the subnet is IPv4, or dual stack.
   1. If you select IPv4,
      1. Enter the IPv4 network address with minimum size of 23 for the external dataplane network. Use this network for external accessible services such as admin clusters and storage interfaces. The network address must be a continuous IP block that is preallocated in your network. For example, 10.100.101.0/23.
   2. If you select dual stack,
      1. Enter the IPv4 network address with minimum size of 23 for the external dataplane network. Use this network for external accessible services such as admin clusters and storage interfaces. The network address must be a continuous IP block that is preallocated in your network. For example, 10.100.101.0/23.
      2. Enter the IPv6 network address with the minimum size of 64. This IP block is divided into two, the first half is used as the external dataplane network and the second half is used as the internal dataplane network. For example, FC00::/64.

Uplink information

Uplink configurations are peering connections used to externally connect GDC air-gapped appliance instances to other services such as customer networks and other GDC air-gapped appliance instances. These uplink configurations and wiring from a GDC air-gapped appliance instance are important to ensure proper connectivity with the external network.

1. Enter the number of uplinks needed for customer peering to the GDC air-gapped appliance instance. If the number you provided does not match the expected number of uplinks, the remaining uplinks are allocated from the external data plane subnet.
2. For the uplinks, specify the following:
   1. Specify the switch name. The name must match the provided switch name in the Device ID (DEID). For example, bc-aa-tesw01.
   2. Specify the port number for the switch name that connects to the uplink network with the applicable peer subnet on that link. The VLAN for this port can be represented as a sub-interface (Eth1/2.x). Acceptable formats include: Eth1/45, eth1/45, Eth1/45.2.
   3. Specify if the IP family subnet is IPv4 or dual stack.
      1. If you select IPv4,
         1. For IPv4, enter the peer subnet block configured on the customer network for the provided switch and port link. This is a /31 subnet. For example, 172.16.255.148/31.
         2. For peerIPv4, enter the IP address representing the customer facing IP address in the /31 peer subnet. For example, 172.16.255.148.
      2. If you select dual stack,
         1. For IPv4, enter the peer subnet block configured on the customer network for the provided switch and port link. This is a /31 subnet. For example, 172.16.255.148/31.
         2. For peerIPv4, enter the IP address representing the customer facing IP address in the /31 peer subnet. For example, 172.16.255.148.
         3. For IPv6, enter the peer subnet block configured on the customer network for the provided switch and port link. This is a /127 subnet. For example, FC00::/127.
         4. For peerIPv6, enter the IP address representing the customer facing IP address in the /127 peer subnet. For example, FC00::.

Optional: External Network Time Protocol (NTP) information

If you use an external NTP server, set up authentication to the server. You must have a symmetric key and a key ID configured on the external NTP server. The relay servers use symmetric keys for server authentication.

1. Specify whether you want to set up an external NTP server. Enter yes to continue or no to skip.
2. Enter a comma-delimited list of IP addresses that represent the external NTP servers, such as 10.0.0.123 or 10.0.0.124.
3. Specify whether you want to configure an external NTP authentication secret. Enter yes to specify an external authentication symmetric key or no to skip.
4. Enter the ID of the external NTP authentication key. This ID must match the ID value that is configured on the external NTP server.
5. Enter the type of the external NTP authentication key, such as MD5, SHA1 SHA256, or SHA512.
6. Enter the external NTP authentication symmetric key. Specify this value in hexadecimal string format.

Optional: External hardware security module (HSM) information

HSM devices host encryption keys and perform cryptographic operations using KMIP (Key Management Interoperability Protocol). You can use HSM with software-defined storage.

1. Specify whether you want to use an external HSM device. Enter yes to to specify the HSM details or no to skip.
2. Specify whether you want to provide HSM details for an IP or DNS name.
   • If you selected IP, enter the IP network address of the KMIP service. For example, 8.8.8.8.
   • If you selected DNS name, enter the fully qualified domain name of the KMIP service. For example, te.us-central1-a.
3. Enter the port number of the KMIP service.
4. Enter the encryption key ID.
5. Enter the CACert. The CA cert is the signed certificate for the KMIP service.
6. Enter the client certificate for connecting to the external HSM.
7. Enter the client key associated with the client certificate for connecting to the external HSM.

Optional: Connect an identity provider

You can connect to your own existing identity provider (IdP) for identity and access management or automatically set up a built-in Keycloak IdP.

1. Specify whether you want to use your own identity provider or install the built-in Keycloak IdP that is available with GDC air-gapped appliance. Enter yes to provide the details of your own IdP or no to use the built-in IdP. If you select the built-in identity provider, the following questions are skipped.
2. Choose the type of identity provider that you are connecting to: OIDC (OpenID Connect) or SAML (Security Assertion Markup Language).
3. If you choose an OIDC provider, specify the following parameters:
   1. Enter the name of the IdP. The name that you provide here is the alias of the identity in the system.
   2. Enter the issuer URI. The issuer URI must point to the level inside .well-known/openid-configuration. Client applications send authorization requests to this URL. The Kubernetes API server uses this URL to discover public keys for verifying tokens.
   3. Enter a base64-encoded PEM-encoded certificate for the certificate authority data for the IdP. For more information, see https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail.
      1. To create the string, encode the certificate, including headers, into base64.
      2. Include the resulting string as a single line. Example: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tC...k1JSUN2RENDQWFT==
   4. Enter the client ID for the client application that makes authentication requests to the IdP.
   5. Enter the client secret, which is a shared secret between your IdP and GDC air-gapped appliance.
   6. Enter the user claim field to identify each user. This is the name of the claim in the OIDC ID Token that holds the username. If this claim is missing from the ID Token, users cannot authenticate. The default claim for many providers is sub. You can choose other claims, such as email or name, depending on the identity provider. Claims other than email are prefixed with the issuer URL to prevent naming clashes.
   7. If your identity provider requires additional scopes, enter a comma-separated list of scopes to send to the IDP. For example, Microsoft Azure and Okta require the offline_access scope.
4. If you choose a SAML provider, specify the following parameters:
   1. Enter the name of the IdP. The name that you provide here is the alias of the identity in the system.
   2. Enter the entity ID for the SAML provider, specified in a URI format, such as: https://www.idp.com/saml.
   3. Enter the SSO URI, which is the URI to the SAML provider's SSO endpoint, such as https://www.idp.com/saml/sso.
   4. Enter a comma-separated list of the IDP certificates used to verify the SAML response. These certificates must be standard Base64 encoded and PEM formatted. A maximum of two certificates are supported to facilitate IDP certificate rotation.
   5. Enter the user attribute, which is the name of the attribute in the SAML response that holds the username. If this attribute is missing from the SAML response, authentication fails.

5. If you connect to your own IdP, enter the account for the initial admin. The initial admin is the first account that is granted access to the system after the installation is complete. The value that you enter must match the claim type, such as an email address if the user claim for an OIDC provider is set to email.

   Record the name of the initial admin, as you need this information to log in to the system for the first time after the installation is complete.

The command generates a cell config directory to the file system for the appliance.

Back up the config

Make a backup of the cellcfg directory from /path/to/cellcfg generated by the command.

Important: You must provide the saved cellcfg directory to update and patch the appliance.

Install the appliance software

Run the following command on the laptop to install the remaining software.

gdcloud appliance install

This command reads the config directory generated by the gdcloud appliance configure command and installs the remaining software, for example the container registry and the admin cluster.

Back up emergency credentials

After the admin cluster is installed, the kubeconfig for the root admin cluster is available at /root/release/root-admin/root-admin-kubeconfig on bm02. Back up the kubeconfig as the emergency credential. You can also use the root kubeconfig file to get the org-admin kubeconfig and system cluster kubeconfigs later.

Optional: Record initial credentials for built-in identity provider

If you did not connect to your own identity provider in the gdcloud appliance config step, a Keycloak IdP is automatically installed and configured.

This phase of the installation prints out the following items:

• The credentials for the Keycloak local admin and the initial user. The local admin for the built-in IDP is admin, which is the Keycloak admin used inside the Keycloak admin console. The initial user is initial-user, used in GDC air-gapped appliance.
• The Keycloak URL.

1. Record these credentials to use them when logging in to the built-in IdP for the first time.

   Note: The credentials printed out are the initial credential pairs and are not valid after they are changed by users.

2. Save the generated credentials after the installation is complete.

If the credentials for the initial user and local admin of the built-in IDP are not printed out during the installation process, get the credentials by running this command:

gdcloud appliance install --phase=identity-provider

To add more users in the Keycloak admin console, see the Keycloak documentation for managing users at https://www.keycloak.org/docs/latest/server_admin/#assembly-managing-users_server_administration_guide.

Manage YubiKeys

After the installation completes, the YubiKeys must stay in the server until you return the system.

What's next

Configure firewall rules