Install on AWS

info

Please view the Prerequisites and ensure you have met all requirements before proceeding with the installation.

Install Wayfinder

The terraform-aws-wayfinder Terraform Module can be used to provision and manage a licensed edition of Appvia Wayfinder on AWS.

Follow the steps below to get up and running quickly, using the predefined quickstart example.

Configure

1. Within your AWS Account, create a Route53 Public Hosted Zone which can be used for the Wayfinder Portal and API DNS Records.
2. Clone down the terraform-aws-wayfinder repository and navigate to examples/quickstart, or copy the contents of this directory to your local machine.
3. Copy the terraform.tfvars.example file to terraform.tfvars and populate the variables with your own values.

Deploy

1. Authenticate to AWS using the AWS CLI.
2. Run terraform init to initialise the Terraform modules.
   • If you are using S3 as a backend, you will need to provide the relevant variables to the init command, e.g.

     terraform init -upgrade \
         -backend-config="bucket=<S3_BUCKET>" \
         -backend-config="key=wayfinder.tfstate" \
         -backend-config="encrypt=true" \
         -backend-config="dynamodb_table=<DYNAMODB_TABLE>" \
         -backend-config="region=eu-west-2"
3. Run terraform plan -out=wayfinder.tfplan to view the resources that will be created.
4. Run terraform apply wayfinder.tfplan

Advanced Configuration

Retrieve licence key from AWS Secrets Manager

Rather than passing the Wayfinder licence key directly to the Terraform module, you can store it in AWS Secrets Manager and retrieve it using the Terraform AWS provider:

1. Create an AWS Secrets Manager Secret containing the Wayfinder licence key:

   aws secretsmanager create-secret --name wayfinder-secrets
   
   cat secret.json
   {
   "licenceKey": "LICENCE-KEY"
   }
   
   aws secretsmanager put-secret-value --secret-id wayfinder-secrets --secret-string file://secret.json
2. Update the wayfinder_licence_key variable to retrieve the licence key from AWS Secrets Manager:

data "aws_secretsmanager_secret" "wayfinder" {
    name = "wayfinder-secrets"
}

data "aws_secretsmanager_secret_version" "wayfinder" {
    secret_id = data.aws_secretsmanager_secret.wayfinder.id
}

module "wayfinder" {
    ...
    wayfinder_licence_key = jsondecode(data.aws_secretsmanager_secret_version.wayfinder.secret_string)["licenceKey"]
}

Configure an Identity Provider (IDP)

If you have an existing IDP, you can configure it during installation by providing the Client ID, Client Secret and Server URL (or Azure Tenant ID) as variables to the module. The Terraform code below shows an example of how to do this, sourcing values from AWS Secrets Manager and disabling the creation of the local administrator user in the process:

module "wayfinder" {
    ...
    create_localadmin_user = false
    wayfinder_idp_details  = {
        type          = var.idp_provider
        clientId      = jsondecode(data.aws_secretsmanager_secret_version.wayfinder.secret_string)["idpClientId"]
        clientSecret  = jsondecode(data.aws_secretsmanager_secret_version.wayfinder.secret_string)["idpClientSecret"]
        serverUrl     = var.idp_provider == "generic" ? jsondecode(data.aws_secretsmanager_secret_version.wayfinder.secret_string)["idpServerUrl"] : ""
        azureTenantId = var.idp_provider == "aad" ? jsondecode(data.aws_secretsmanager_secret_version.wayfinder.secret_string)["idpAzureTenantId"] : ""
    }
}

Use an existing VPC

If you have an existing VPC and Subnets (e.g. one already connected to your corporate VPN), you can deploy Wayfinder into your own network by providing the VPC ID and Subnet IDs as variables to the main module:

module "wayfinder" {
    ...
    subnet_ids = ["subnet-123456789", "subnet-987654321"]
    vpc_id     = "vpc-123456789"
}

Additionally, you can set disable_internet_access = true to make the EKS API, Wayfinder API and Portal only accessible from within your corporate network (not exposed via public load balancers).

info

When deploying Wayfinder into your own network, you will need to ensure that the following tags are applied to the relevant subnets:

1. Public Subnets should have the tag "kubernetes.io/role/elb" = 1
2. Private Subnets should have the tag "kubernetes.io/role/internal-elb" = 1

Access Wayfinder EKS Management Cluster

If you need to access the Wayfinder EKS Management Cluster (e.g. for debugging purposes, providing logs to Appvia Support), you can do so by running the following command:

aws eks --region <REGION> update-kubeconfig --name <EKS_MANAGEMENT_CLUSTER_NAME>

info

When provisioning the EKS Management Cluster via this Terraform Module, the identity or role ARN used to authenticate to the AWS API will be granted administrator access to the cluster. If this was run via CI, you must assume the same role that was used in CI to gain access to the management cluster. Instructions on how to do this are available within the prerequisites docs.