Installing a Phalanx environment#

Once you have created the configuration for your new environment and set up secrets, you are ready to do the installation. Before starting this process, ensure that you have met the requirements to run Phalanx.

If you are setting up an environment that will be running a 1Password Connect server for itself, you will need to take special bootstrapping steps. See onepassword-connect for more information.

Installing Phalanx#

Follow these steps to install Phalanx. These can be run repeatedly to reinstall Phalanx over an existing deployment.

  1. Create a Vault AppRole that will be used by Vault Secrets Operator. Set the VAULT_TOKEN environment variable to a token with the ability to create new AppRoles (for SQuaRE clusters, use the admin token), and then run:

    phalanx vault create-read-approle <environment>

    Unset VAULT_TOKEN when this command finishes.

    Be aware that this will invalidate any existing AppRole for that environment.

  2. Set the environment variables VAULT_ROLE_ID and VAULT_SECRET_ID to the Role ID and Secret ID printed out by that command.

  3. Ensure that your default Kubernetes cluster for kubectl and helm is set to point to the Kubernetes cluster into which you want to install the Phalanx environment. You can verify this with kubectl config current-context.

  4. Start the install:

    phalanx environment install <environment>

    You will be prompted to confirm that you want to proceed.

  5. If the installation is using a dynamically-assigned IP address, you will need to set up the A record (and AAAA record if using IPv6) in DNS once that address has been assigned. Wait until the ingress-nginx application has been installed, which happens after Argo CD has been installed but before most applications are synced. Then, wait for it to be assigned an external IP address. Obtain that IP address with kubectl get -n ingress-nginx service (look for the external IP). Then, set the A record in DNS for your environment to that address. For installations that are intended to be long-lived and that can reliably request the same address, add that IP address to the values-environment.yaml file in applications/ingress-nginx for your environment. The setting to use is ingress-nginx.controller.service.loadBalancerIP. This ensures that ingress-nginx will always request that address.

  6. If you are deploying on Google Cloud Platform, consider converting the dynamically-assigned IP address to a static IP. You can do this in the GCP console under VPC Network -> IP addresses.

  7. Debug any problems during installation. The most common source of problems are errors or missing configuration in the values-environment.yaml files you created for each application. You can safely run the installer repeatedly as you debug and fix issues.

Using a Vault token rather than AppRole#

The default and recommended installation approach is to use a Vault AppRole for vault-secrets-operator to authenticate to Vault. However, using a read-only Vault token is still supported.

To use a Vault token instead of an AppRole, create an appropriate read-only token with access to the Vault path configured in enviroments/values-environment.yaml for your environment. Skip step 1 in the normal installation process, since you don’t need to create an AppRole. In step 2, set VAULT_TOKEN to the read-only token and do not set VAULT_ROLE_ID or VAULT_SECRET_ID. Then continue the regular installation process.

Troubleshooting tools#

The tools to use for troubleshooting will vary depending on how far the installer has gotten.

  • If something fails before Argo CD is installed, you will need to use kubectl to look around in Kubernetes, retrieve logs, and look at error messages.

  • If Argo CD is installed and working, but ingress-nginx fails, you can additionally use the argocd command-line tool. The installer will have created login credentials for Argo CD as the admin user for you, so you shouldn’t need to do that again. Pass the flags --port-forward --port-forward-namespace argocd to argocd to proxy to the Argo CD server without needing to have the ingress working.

  • If the ingress was successfully installed and you’ve created the DNS record for your environment, you can use the Argo CD web UI the same as you would with a fully-installed cluster. If your Argo CD authentication configuration is working (see Argo CD authentication), you can log in as you normally would. If it is not, you will need to use the admin password. You can get this from Vault in the admin.plaintext_password key of the argocd secret.