Private Cloud - Installation (AWS)

This guide walks you through installing Pangea's security services in your AWS cloud environment using MacOS X. The installation process involves setting up necessary components, configuring your environment, and validating the installation to ensure everything works correctly.

Overview of installation process

Before diving into the specific steps, here's what you'll be doing:

Setting up the initial package and verifying its contents
Configuring your installation parameters
Running the installation and verifying it worked
(Optional) Updating or uninstalling if needed

Installation steps

1. Download and extract installation package

This step obtains and unpacks the core installation files needed to set up your Private Cloud environment.

# Download the installation package from [DOWNLOAD_LINK]
tar xf pangea-private-cloud.tar.gz
cd pangea-private-cloud

Why this step matters:

The package contains all necessary configuration files and scripts
Extracting preserves file permissions which are crucial for the installation
The working directory must be the extracted folder for relative paths to work correctly

2. Package contents overview

Understanding the package contents helps you know which files you'll be working with and their purposes:

.
├── data/
│   ├── crds.yml          # Core Custom Resource Definitions
│   └── us_itar.json      # ITAR compliance configurations
├── serviceconfig/
│   └── examples/         # Service configuration examples
│       └── embargo_service_config_custom_lists.yml
├── pangea-private-cloud.sh  # Installation script
├── pangeacluster.yml        # Cluster configuration template (created after first run)
└── pangeadbspec.yml         # Database specifications (created after first run)
└── embargo_service_config.yml        # Embargo service configuration (created after first run)
└── intelligence_service_config.yml        # Intelligence service configuration (created after first run)

Key files explained:

crds.yml: Defines custom resources needed by Kubernetes to understand Pangea's services.
us_itar.json: Contains International Traffic in Arms Regulations compliance settings.
pangea-private-cloud.sh: Main installation script that orchestrates the entire process.
pangeacluster.yml: Where you'll configure your specific installation needs.
pangeadbspec.yml: Database configuration settings and requirements.
embargo_service_config.yml: Configures the embargo service.
intelligence_service_config.yml: Configures the file-intel service.

Shell Script Commands

Switch	Argument	Description
`-h`	None	Displays the usage instructions and exits the script.
`-n`	`<namespace>`	Specifies the Kubernetes namespace to be used for the operations. Default is `default`.
`-u`	None	Sets the operation mode to `uninstall`, triggering the script to uninstall the Pangea Cloud setup.
`-v`	`<version>`	Specifies the version of the Pangea Private Cloud to install. Defaults to `0.7.14`.

Usage:

Basic Installation

# Install in default namespace
./pangea-private-cloud.sh

# Install in specific namespace
./pangea-private-cloud.sh -n pangea-dev

Version Control

# Install specific version
./pangea-private-cloud.sh -n pangea-prod -v 0.7.14

# Update existing installation to new version
./pangea-private-cloud.sh -n pangea-prod -v 0.7.15

Uninstallation

# Remove from specific namespace
./pangea-private-cloud.sh -n pangea-dev -u

Getting Help

# Display usage instructions
./pangea-private-cloud.sh -h

important

If no options are provided, the script will:

Use the default namespace
Install version 0.7.12
Perform an installation operation

warning

The -v (version) switch cannot be used with -u (uninstall) as version specification isn't relevant during uninstallation.

3. Configure your installation

Edit pangeacluster.yml to customize your installation:

Database connection details: Ensure your database can be accessed by the services
Service selection: Choose which Pangea services you want to deploy
Registry configuration: Specify where to pull container images from

Why proper configuration matters:

Incorrect database settings can prevent services from starting
Missing services won't be available post-installation
Wrong registry settings can prevent image pulls

4. Run the installation

The installation script handles the complex process of setting up your Private Cloud environment.

# Install latest version
./pangea-private-cloud.sh -n <namespace>

# Or install specific version
./pangea-private-cloud.sh -n <namespace> -v <version>

note

If you're unsure which namespace to use, consider:

Checking existing namespaces with kubectl get namespaces to avoid conflicts.
Consulting your team's naming conventions.
Starting with pangea-test for initial deployments.

What the script does:

Verifies prerequisites (Helm, AWS CLI)
Sets up necessary Kubernetes resources
Deploys selected services
Configures networking and security

5. Verify the installation worked

Check that everything is deployed correctly before proceeding.

kubectl get pangeacluster -n <namespace>
kubectl get pods -n <namespace>

What to look for:

All pods should show "Running" status
No pods should be in "CrashLoopBackOff" or "Error" state
The pangeacluster resource should show "Ready"

6. Done!

Now that your installation has completed, you can start using Pangea services to protect your data. Please note that there is a maintenance job that is triggered at the top of the hour, which will take a significant amount of time to complete.

Managing your installation

Updating your installation

Updates allow you to get new features and security patches. The update process is similar to installation but preserves your data and configurations.

./pangea-private-cloud.sh <namespace> <new-version>

Important update notes:

Updates are non-destructive
Your configurations are preserved
Services may experience brief downtime

Uninstalling your installation

If you need to remove Pangea services, the uninstallation process ensures clean removal.

./pangea-private-cloud.sh <namespace> uninstall

What uninstallation does:

Removes all Pangea services
Cleans up Kubernetes resources
Optionally removes data (configurable)
Deletes the namespace

Appendix: Pangea Installer Script

Install

This section describes the steps the Pangea Installer script performs to install and/or update Pangea Private Cloud.

Check Required Tools Ensures helm and the AWS CLI are installed. If not, the script exits with instructions.

brew list awscli >/dev/null 2>&1 || (echo "Must brew install awscli" && exit)
brew list helm >/dev/null 2>&1 || (echo "Must brew install helm" && exit)

Log into ECR Logs into the AWS Elastic Container Registry (ECR) in the us-east-1 region.

aws ecr get-login-password --region us-east-1 | helm registry login --username AWS --password-stdin 227262099132.dkr.ecr.us-east-1.amazonaws.com || (echo "Failed to login to ECR" && exit 1)

Create Namespace Creates a Kubernetes namespace for the cluster. If the namespace already exists, the script proceeds without error.

kubectl create namespace "$NAMESPACE" || (echo "Failed to create namespace: $?" && exit $?)

Install the Helm Chart Installs the Pangea Helm chart. If the chart is already installed, the script checks for version mismatches and upgrades if necessary.

STATUS=$(helm install -n "$NAMESPACE" private-cloud-operator oci://227262099132.dkr.ecr.us-east-1.amazonaws.com/private-cloud-charts --version $VERSION 2>&1)
if [[ $STATUS == *"cannot re-use a name that is still in use"* ]]; then
    get_installed_version
    if [[ $INSTALLED_VERSION != $VERSION ]]; then
        helm upgrade -n "$NAMESPACE" private-cloud-operator oci://227262099132.dkr.ecr.us-east-1.amazonaws.com/private-cloud-charts --version $VERSION || exit $?
    fi
fi

Ensure Helm Controller is Running Validates that the Helm controller is deployed and running.

check_deployment "$NAMESPACE" "Pangea operator" "true" "controller-manager"

Install the Postgres Operator Deploys the Postgres operator. Ensures the operator pod is running before proceeding.

kubectl apply -n "$NAMESPACE" -f pangeadbspec.yml || (echo "Failed to install the Postgres operator" && exit)

while true; do
  STATUS=$(kubectl get pod postgres-0 -n "$NAMESPACE" -o jsonpath='{.status.phase}')
  if [[ $STATUS == "Running" ]]; then
      echo "Postgres pod is running"
      break
  fi
  sleep 5
done

Install the Pangea Cluster Applies the Pangea cluster specification file. Deletes old secrets if upgrading from a previous version.

kubectl apply -n "$NAMESPACE" -f pangeacluster.yml || (echo "Failed to install the Pangea cluster" && exit)

Wait for Service Deployments Waits for all enabled services to be successfully deployed.

check_deployment "$NAMESPACE" "authn" "true" "pangea-cluster-authn"
check_deployment "$NAMESPACE" "gateway" "true" "pangea-cluster-gateway"
check_deployment "$NAMESPACE" "embargo" "$EMBARGO_ENABLED" "pangea-cluster-embargo"
check_deployment "$NAMESPACE" "intelligence" "$FILE_INTEL_ENABLED" "pangea-cluster-intelligence"
check_deployment "$NAMESPACE" "redact" "$REDACT_ENABLED" "pangea-cluster-redact"

Validate Installation Verifies that all expected pods are running in the namespace.

kubectl get pods -n "$NAMESPACE"

Create Service Configurations Generates and applies service-specific configurations, then validates their installation with API queries.

Example for the embargo service:

kubectl apply -n "$NAMESPACE" -f embargo_service_config.yml
until kubectl get secret embargo-config-token -n "$NAMESPACE" &> /dev/null; do
  echo "Waiting for secret embargo-config-token to be created..."
  sleep 10
done

EMBARGO_TOKEN=$(kubectl get secret embargo-config-token -o jsonpath='{.data.api-token}' -n "$NAMESPACE" | base64 -D)
kubectl exec -it $(kubectl get pods -n "$NAMESPACE" | grep embargo | awk '{print $1}') -n "$NAMESPACE" -- /bin/sh -c "curl -X POST 'http://pangea-cluster-gateway.$NAMESPACE.svc.cluster.local:8000/v1/ip/check' -H 'Authorization: Bearer $EMBARGO_TOKEN' -H 'Host: embargo.pangea.cloud' -d '{\"ip\": \"200.0.16.24\"}'"

Note: To manually query the API in case of failure:

Set the Service Token:

SERVICE_TOKEN=$(kubectl get secret embargo-config-token -o yaml | yq .data.api-token | base64 -d)

Call the embargo service API:

kubectl exec -it $(kubectl get pods -n "$NAMESPACE" | grep embargo | awk '{print $1}') -n "$NAMESPACE" -- /bin/sh -c "curl -X POST 'http://pangea-cluster-gateway.$NAMESPACE.svc.cluster.local:8000/v1/ip/check' -H 'Authorization: Bearer $SERVICE_TOKEN' -H 'Host: embargo.pangea.cloud' -d '{\"ip\": \"200.0.16.24\"}'"

Uninstall

Patch and Remove Service Configurations

kubectl patch serviceconfig.cluster.pangea.cloud embargo-config -p '{"metadata":{"finalizers":[]}}' --type=merge -n $NAMESPACE
kubectl delete serviceconfig.cluster.pangea.cloud/embargo-config -n $NAMESPACE

Delete the Pangea Cluster

kubectl patch pangeacluster.cluster.pangea.cloud/pangea-cluster -p '{"metadata":{"finalizers":[]}}' --type=merge
kubectl delete pangeacluster.cluster.pangea.cloud/pangea-cluster -n $NAMESPACE

Remove Custom Resource Definitions

kubectl delete crd pangeaclusters.cluster.pangea.cloud
kubectl delete crd serviceconfigs.cluster.pangea.cloud

Remove Postgres Deployment

kubectl delete postgresql postgres -n $NAMESPACE

Uninstall the Pangea Cloud Operator

helm uninstall -n $NAMESPACE private-cloud-operator

Delete the Kubernetes Namespace

kubectl delete namespace $NAMESPACE

Was this article helpful?

Overview of installation process​

Installation steps​

1. Download and extract installation package​

2. Package contents overview​

Shell Script Commands​

3. Configure your installation​

4. Run the installation​

5. Verify the installation worked​

6. Done!​

Managing your installation​

Updating your installation​

Uninstalling your installation​

Appendix: Pangea Installer Script​

Install​

Uninstall​