Skip to main content

Installing Coginiti Enterprise on GKE (Air-Gapped)

This guide provides comprehensive instructions for installing Coginiti Enterprise on Google Kubernetes Engine (GKE) in an air-gapped environment. This deployment method is designed for organizations with strict network isolation requirements.

Overview​

The deployment process consists of three key stages:

  1. Configuring GCP project and required tools
  2. Provisioning GCP resources within the project
  3. Installing Coginiti Enterprise on the GKE cluster
Enterprise vs Team

This guide is specifically for Coginiti Enterprise deployment on GKE. For Coginiti Team installation, see the Coginiti Team Installation Guide.

Prerequisites​

GCP Account and Project​

  • Valid Google Cloud Platform account
  • New GCP project or existing project designated for Coginiti Enterprise
  • Required IAM roles assigned to your account

Required IAM Roles​

Ensure your account has the following IAM roles in the GCP project:

  • Compute Network Admin (compute.networkAdmin)
  • Artifact Registry Administrator (artifactregistry.admin)
  • DNS Administrator (dns.admin)
  • Certificate Manager Editor (certificatemanager.editor)
  • Kubernetes Engine Cluster Admin (container.clusterAdmin)
  • Cloud SQL Editor (cloudsql.editor)

Installing Required Tools​

Install the following software on your local machine:

1. Google Cloud CLI​

Download and install the Google Cloud CLI from the official documentation. This is required to interact with GCP services via command line.

2. Kubernetes Command-Line Tool (kubectl)​

Follow the installation instructions for your operating system from kubectl installation guide.

3. KOTS CLI​

Install the KOTS kubectl plugin following the KOTS CLI Getting Started guide.

Verify your KOTS installation:

kubectl kots version

Provisioning GCP Resources​

Required Infrastructure Components​

You will need to provision the following GCP resources:

Networking​

  • VPC network - Custom VPC for the deployment
  • Proxy-only Subnet - For Internal Application Load Balancer
  • Internal Static IP address - Used by Internal ALB and DNS

Compute and Storage​

  • Private VPC-native GKE cluster - Kubernetes cluster for Coginiti Enterprise
  • PostgreSQL server - Database backend with pg_vector extension
  • Artifact Registry Repository - Container images storage

Security and DNS​

  • DNS zone and DNS name - Domain configuration for Coginiti Enterprise
  • Self-Managed SSL Certificate - For HTTPS communication

GKE Cluster Requirements​

  • Kubernetes Version: 1.27 or higher
  • Node Configuration: Minimum 3 nodes of n2-standard-8 type
  • Storage: pd-balanced persistent disk, minimum 256 GB per node
  • Required Addons: HorizontalPodAutoscaling, HttpLoadBalancing, GcePersistentDiskCsiDriver
  • Gateway API: Gateway API must be enabled on the cluster in GCP console or via CLI command:
gcloud container clusters update CLUSTER_NAME \
    --location=CLUSTER_LOCATION \
    --gateway-api=standard

PostgreSQL Requirements​

  • Version: PostgreSQL 15 or 16
  • Extensions: pg_vector extension must be installed
  • Connectivity: Accessible from the GKE cluster
  • Database: Dedicated database for Coginiti application

Step-by-Step Infrastructure Setup​

If you haven't deployed GCP resources yet, use these commands to set up the required infrastructure:

1. Create VPC Network​

gcloud compute networks create coginiti-net \
  --subnet-mode custom

2. Create Private Subnet​

gcloud compute networks subnets create coginiti-cluster-snet \
  --network coginiti-net \
  --range 192.168.0.0/28 \
  --secondary-range my-pods=10.1.0.0/20,my-services=10.1.16.0/24 \
  --enable-private-ip-google-access \
  --region={REGION}

Replace {REGION} with your chosen Google Cloud region.

IP Address Planning

Decide on primary and secondary IP address ranges according to your intended network design and topology.

3. Create Proxy-Only Subnet for Internal ALB​

gcloud compute networks subnets create coginiti-proxy-only-snet \
  --network coginiti-net \
  --range 192.168.1.0/26 \
  --purpose REGIONAL_MANAGED_PROXY \
  --role ACTIVE \
  --region={REGION}

4. Add Firewall Rule for Proxy Connection​

gcloud compute firewall-rules create allow-proxy-connection \
  --network coginiti-net \
  --allow TCP:8080 \
  --source-ranges 192.168.1.0/26

5. Create Internal Static IP Address​

gcloud compute addresses create coginiti-internal-ip \
  --subnet=coginiti-cluster-snet \
  --purpose=GCE_ENDPOINT \
  --region={REGION}

6. Create Private Cloud DNS Zone​

gcloud dns managed-zones create coginiti \
  --dns-name example.com. \
  --description="Private DNS Zone for Coginiti Enterprise" \
  --visibility private \
  --networks coginiti-net
Domain Ownership

You must own the domain name used for the DNS zone. Replace example.com with your actual domain.

7. Get Internal Static IP Address​

gcloud compute addresses describe coginiti-internal-ip \
  --region={REGION}

8. Add DNS A Record​

gcloud dns record-sets transaction start \
  --zone=coginiti

gcloud dns record-sets transaction add {STATIC_INTERNAL_IP} \
  --name=coginiti.example.com \
  --ttl=300 \
  --type=A \
  --zone=coginiti

gcloud dns record-sets transaction execute --zone=coginiti

Replace {STATIC_INTERNAL_IP} with the IP address from step 7.

Verify the record was added:

gcloud dns record-sets list --zone=coginiti

9. Create Self-Managed SSL Certificate​

gcloud compute ssl-certificates create coginiti-certificate \
  --certificate={PATH_TO_CERTIFICATE_FILE} \
  --private-key={PATH_TO_PRIVATE_KEY_FILE} \
  --region={REGION}

Replace the paths with your SSL certificate and private key file locations, and {REGION} with your deployment region.

SSL Certificate Requirements
  • Must be PEM-encoded format
  • Certificate must match your domain name
  • Must be a regional certificate (not global) for Internal ALB
  • Google-managed SSL certificates cannot be used for Internal ALB

10. Create Artifact Registry​

gcloud artifacts repositories create coginiti-repo \
  --location {REGION} \
  --repository-format docker

11. Get Authentication Token​

TOKEN=$(gcloud auth print-access-token)
Token Lifetime

This token has a one-hour lifetime. You may need to regenerate it during the deployment process.

Upload Container Images to Artifact Registry​

1. Access Application Download Portal​

Contact your Coginiti support team to obtain:

  • Credentials for the Application Download portal
  • Link to the Application Download portal

2. Download Required Bundles​

In the Application Download portal:

  1. Select "Bring my own cluster" option
  2. Choose your desired Coginiti Enterprise version
  3. Download the KOTS Admin Console Bundle
  4. Download the App Bundle (airgap bundle)

3. Push Images to Artifact Registry​

Execute these commands to upload the container images:

kubectl kots admin-console push-images {PATH_TO_ADMIN_BUNDLE} \
  {REGION}-docker.pkg.dev/{PROJECT_NAME}/coginiti-repo \
  --registry-username oauth2accesstoken \
  --registry-password $TOKEN

kubectl kots admin-console push-images {PATH_TO_AIRGAP_BUNDLE} \
  {REGION}-docker.pkg.dev/{PROJECT_NAME}/coginiti-repo \
  --registry-username oauth2accesstoken \
  --registry-password $TOKEN

Replace {REGION}, {PROJECT_NAME}, {PATH_TO_ADMIN_BUNDLE}, and {PATH_TO_AIRGAP_BUNDLE} with your actual values.

Deploy PostgreSQL Server​

1. Allocate IP Address Range for VPC Peering​

gcloud compute addresses create google-managed-services-coginiti-net \
  --purpose=VPC_PEERING \
  --addresses=192.168.3.0 \
  --prefix-length=24 \
  --network=projects/{PROJECT_NAME}/global/networks/coginiti-net \
  --global

2. Create Private Connection​

gcloud services vpc-peerings update \
  --service=servicenetworking.googleapis.com \
  --ranges=google-managed-services-coginiti-net \
  --network=coginiti-net \
  --project={PROJECT_NAME} \
  --force

3. Create PostgreSQL Instance​

gcloud sql instances create coginiti-pg-server \
  --database-version=POSTGRES_15 \
  --cpu=2 \
  --memory=7680MB \
  --network=coginiti-net \
  --no-assign-ip \
  --region={REGION}

4. Set PostgreSQL User Password​

gcloud sql users set-password postgres \
  --instance=coginiti-pg-server \
  --password={YOUR_PASSWORD}

5. Create Coginiti Database​

Connect to the PostgreSQL server and run:

CREATE DATABASE coginiti_db;

6. Install pg_vector Extension​

Connect to the Coginiti database and run:

CREATE EXTENSION vector;

Deploy Private GKE Cluster​

1. Create GKE Cluster​

gcloud container clusters create coginiti-private-cluster \
  --location {REGION} \
  --network coginiti-net \
  --subnetwork coginiti-cluster-snet \
  --cluster-secondary-range-name my-pods \
  --services-secondary-range-name my-services \
  --enable-private-nodes \
  --enable-ip-alias \
  --master-ipv4-cidr 192.168.0.32/28 \
  --machine-type "n2-standard-8" \
  --num-nodes "3"

2. Enable Authorized Networks (Simplified Access)​

gcloud container clusters update coginiti-private-cluster \
  --location {REGION} \
  --enable-master-authorized-networks \
  --master-authorized-networks $(curl ifconfig.me)/32

3. Get Cluster Credentials​

gcloud container clusters get-credentials coginiti-private-cluster \
  --location {REGION}

Install Coginiti Enterprise​

1. Update Authentication Token and Install​

TOKEN=$(gcloud auth print-access-token)

kubectl kots install coginiti-premium/enterprise-release \
  --kotsadm-registry {REGION}-docker.pkg.dev/{PROJECT_NAME} \
  --kotsadm-namespace coginiti-repo \
  --registry-username oauth2accesstoken \
  --registry-password $TOKEN

The installation process will:

  • Validate registry information
  • Deploy the Admin Console
  • Create the namespace
  • Wait for datastore to be ready
  • Prompt for admin console password (6+ characters)

2. Access Admin Console​

The installer will provide a URL. Keep the terminal session open as it provides port-forwarding.

If you accidentally close the terminal, restore access with:

kubectl kots admin-console --namespace {NAMESPACE}

Navigate to http://localhost:8800 in your browser.

Configure Coginiti Enterprise​

1. Admin Console Login​

Enter the password you provided during installation.

2. Upload License File​

Upload the license file provided by your Coginiti support team or download it from the Application Download portal.

3. Configure Artifact Registry Connection​

  • Password: Enter the output of gcloud auth print-access-token
  • Registry Settings: Configure your Artifact Registry details
  • Disable Pushing Images: Check this option since images are already uploaded
  • Upload Bundle: Select and upload the Coginiti Enterprise airgap bundle

4. Configure Superuser Account​

Create the primary administrator account:

  • Superuser Name: Admin username for Coginiti Enterprise
  • Superuser Password: Strong password (minimum 8 characters)

5. Database Configuration​

Get the PostgreSQL server IP address:

gcloud sql instances describe coginiti-pg-server

Configure database connection:

  • Postgres Host Type: Select "Postgres IP Address"
  • Postgres Instance IP Address: Enter the PostgreSQL server IP
  • Database Name: coginiti_db
  • Username: postgres
  • Password: Password set during PostgreSQL configuration

6. Encryption Configuration​

Choose "Generate Encryption key and JWT secret" for new installations.

Critical Security Information

SAVE YOUR ENCRYPTION KEY AND JWT SECRET securely. These are required for:

  • System reinstallation
  • Data recovery from backups
  • Infrastructure migration

Without these keys, encrypted data cannot be recovered.

7. Domain and SSL Configuration​

Configure your production settings:

  • Ingress Hostname: Your Coginiti domain (e.g., coginiti.example.com)
  • GCP Managed Certificate Name: coginiti-certificate
  • Regional Static Internal IP Address Name: coginiti-internal-ip
  • Storage Class: standard-rwo

8. Preflight Checks​

The admin console will validate your configuration:

  • ✅ Required Kubernetes Version
  • ✅ Minimum 3 nodes in cluster
  • ✅ Container Runtime
  • ✅ Kubernetes environment check
  • ✅ Required storage classes
  • ✅ CPU cores requirement (6 or greater)
  • ✅ PostgreSQL 15.x or later
  • ✅ Private Registry Images Available

9. Deploy Application​

Click "Deploy" when preflight checks pass. Monitor the deployment progress in the admin console.

Post-Installation Verification​

1. Access Coginiti Enterprise​

Navigate to your configured domain (e.g., https://coginiti.example.com) and log in with the superuser credentials.

Air-Gapped Access Requirements

Since this is an air-gapped deployment with internal load balancer and private DNS, access to Coginiti Enterprise requires one of the following:

  • VPN Connection: Connect to your GCP VPC via Cloud VPN or third-party VPN
  • Bastion Host: Access through a jump server/bastion host within the VPC
  • Cloud IAP: Use Google Cloud Identity-Aware Proxy for secure access
  • Private Network: Direct connection from on-premises network connected to GCP VPC

The application is not accessible from the public internet.

2. Verify License Application​

The Coginiti Enterprise license should be automatically applied. Verify:

  • License information appears correctly
  • User limits match your license agreement
  • Expiration date is accurate

3. Initial Configuration​

Complete these setup tasks:

  • Configure user accounts and permissions
  • Set up database connections to your data sources
  • Configure authentication (SSO, LDAP if required)
  • Test basic functionality with sample queries

Troubleshooting​

Common Issues​

Authentication Token Expiration​

Symptoms: Registry authentication failures during deployment

Solution: Regenerate the authentication token:

TOKEN=$(gcloud auth print-access-token)

PostgreSQL Connection Issues​

Symptoms: Database connectivity errors during configuration

Solutions:

  1. Verify PostgreSQL instance is running
  2. Check VPC peering configuration
  3. Confirm pg_vector extension is installed
  4. Verify database user permissions

SSL Certificate Problems​

Symptoms: Certificate validation errors

Solutions:

  1. Verify certificate format is PEM-encoded
  2. Ensure certificate matches your domain name
  3. Confirm private key corresponds to certificate
  4. Check certificate expiration date

Admin Console Access Issues​

Symptoms: Cannot access admin console

Solutions:

  1. Verify kubectl context is set correctly
  2. Check port-forwarding is active
  3. Ensure admin console pod is running: 
    kubectl get pods -n {NAMESPACE}

Getting Help​

For installation support:

  • Primary Contact: Your Coginiti Account Manager
  • Technical Support: support@coginiti.co
  • Documentation: Latest installation guides and troubleshooting resources

When contacting support, provide:

  • GCP project details and region
  • Kubernetes cluster configuration
  • Complete error messages and logs
  • Network topology and security configurations

Summary​

You have successfully installed Coginiti Enterprise on GKE in an air-gapped environment! Key achievements:

✅ Infrastructure: GCP resources provisioned with private networking and internal load balancer ✅ Database: PostgreSQL with pg_vector extension configured ✅ Kubernetes: Private GKE cluster with no internet connectivity ✅ Container Images: Successfully uploaded to private Artifact Registry ✅ Application: Coginiti Enterprise deployed and configured ✅ Security: Encryption keys generated and SSL certificate configured for internal access ✅ Network Isolation: Complete air-gapped deployment with private DNS and internal-only access

Your Coginiti Enterprise instance is now ready for production use in your air-gapped environment. Access is restricted to private network connections only (VPN, bastion host, or Cloud IAP).