Skip to main content
Version: latest

Installation and Configuration

note

The following instructions assume the user is proceeding from:

  1. A completed platform setup.
  2. A stable build of cortex-charts.
  3. The installation is being performed on a Linux/MAC OS.
  4. A Kubernetes cluster exists and sizing analysis has been done. (Default: 3 nodes with 4 cpus x 16 GB RAM)

Dependencies Compatibility Matrix Cortex Fabric​

Cortex Helm ChartHelmKubernetesIstioRedisMongoDex
6.4.13.x1.26.x1.17.x7.0.x6.0.x2.36.x
6.4.03.x1.23.x1.15.x7.0.x5.0.x2.36.x
6.3.33.x1.23.x1.13.x6.2.x5.0.x2.32.x
6.3.03.x1.21.x1.13.x6.2.x5.0.x2.32.x
6.2.23.x1.21.x1.12.x6.2.x5.0.x2.31.x
6.2.13.x1.21.x1.12.x6.2.x4.4.x2.31.x
6.2.03.x1.21.x1.12.x6.2.x4.4.x2.31.x
6.1.13.x1.21.x1.12.x6.2.x4.4.x2.31.x
6.1.03.x1.21.x1.12.x6.2.x4.4.x2.31.x

Users have a choice of internal storage including: MinIO, S3, or GCS storage.

NOTE: Version 6.3.1 and 6.3.2 were internal-only releases.

Prerequisites​

Cortex Helm installation can be performed on the following platforms. Follow the links to view prerequisites that must be in place prior to performing the steps for Cortex Fabric Helm installation on a Kubernetes cluster.

note

Creating hosted-externalized infrastructure dependencies (especially Mongo, Redis, and MinIO) is considered the best practice for both development and production environments of Cortex Fabric.

Customers who opt for this setup are responsible for creating accounts with the dependency providers, procuring the required licenses, implementing appropriate plans for their solutions, monitoring their usage, and managing those accounts.

Examples of externalized dependency setup are provided in the Cortex Charts here.

For development/demo environments customers may opt to install Cortex with the internalized dependencies as directed in the Installation Guide below.

Redis, Mongo, Dex, and Minio are packaged in the Fabric Helm Chart as internalized dependencies.

Read the following instructions for using Kubernetes and Dex.

Cortex URLs​

After your base-domain is set up, you will use it to access Cortex tools:

The Fabric URL is https://api.<base-domain>. Use the URL to open the Cortex Fabric Console and in REST API calls headers.

For instructions to install Cortex Fabric tools, see https://cognitivescale.github.io/cortex-fabric/

Ports​

Fabric sets up resources (Istio Gateway) that allow ingress traffic on the following ports:

TypePortDescriptionRequired
https443for accessing Fabric APIsRequired
http80for http->https redirectsOptional
status15021for Istio gateway (service mesh) healthcheck; shows if the service mesh is functioning, but is not a measure of system up/down.Optional

Install Fabric​

  1. Create a values file (values.yaml) for your specific deployment variables. The links below provide detailed instructions and best practices for working with Helm charts.

     cortex:
     # cortex.imageRegistry: Source docker registry to pull cortex service images from, default is dockerhub
       imageRegistry: index.docker.io/
       dex:
         autoscaling:
           enabled: false
         config:
           issuer: "https://api.<BASE_DOMAIN>/dex"
         staticClients:
         - id: cortex-app
           redirectURIs:
           - "https://api.<BASE_DOMAIN>/login/oidc"
       domains:
         base: <BASE_DOMAIN>

  2. Add Cortex Helm Repository to Helm repo cache.

    helm repo add cortex https://cognitivescale.github.io/cortex-charts/stable

  3. Create a namespace for Cortex installation.

    • cortex services namespace:
      kubectl create namespace cortex
    • cortex-compute namespace:
      kubectl create namespace cortex-compute

  4. Create secrets for Cortex deploy. Needed only when pulling Cortex images from DockerHub.

    For cortex namespace:

    kubectl create secret docker-registry docker-login \
      --docker-server=<docker_registry> \
      --docker-username=<docker_username> \
      --docker-password=<docker_password> \
      -n cortex

    For cortex-compute namespace:

    kubectl create secret docker-registry docker-login \
      --docker-server=<docker_registry> \
      --docker-username=<docker_username> \
      --docker-password=<docker_password> \
      -n cortex-compute
    note

    Use https://index.docker.io/v1/ for docker_registry. If you are using ECR or ACR, provide entries in the values file for proper Docker image locations.

  5. Deploy Cortex via Helm chart. The recommended way to use SSL certificate is as shown below. To know more on how to format the certs or debug issues with SSL certificate refer to [Istio Docs] (https://istio.io/latest/docs/tasks/security/cert-management/plugin-ca-cert/#verifying-the-certificates)

    helm upgrade --install cortex \
      cortex/fabric6 \
      --namespace cortex \
      -f cortex.yaml \
      --set cortex.ssl.cert="$(cat cert.crt)" \
      --set cortex.ssl.key="$(cat key.pem)"

    To deploy a specific version of the Cortex Helm chart use the --version argument and specify the version number.

    helm upgrade --install cortex \
      cortex/fabric6 \
      --namespace cortex \
      -f cortex.yaml \
      --set cortex.ssl.cert="$(cat cert.crt)" \
      --set cortex.ssl.key="$(cat key.pem)" \
      --version 0.6.x

Verify deployment status​

Verify that the pods are deployed and stable in the namespace Fabric was deployed to by using one of the two utilities (or any other Kubernetes utility):

Your pods must be running and stable before moving on to the post deployment steps.

Post Deployment Steps​

  1. (Optional) Deploy the metrics-service to track node and pod metrics.

    NOTE: Not needed for AKS as "metrics-server" is deployed as part of the default K8s services

  2. (Only required if external-dns is not configured via cortex.yaml) Create A-record or CNAME DNS entry for * (/ wildcard) that points to the deployed ingress controller public IP address AND create A-record or CNAME DNS entry for "private-registry" that points to the secondary docker-ingress controller public IP address.

    Identify Istio-ingress service controller public IP address and use it to configure the Route 53 or DNS mapping records.

  1. Enable authentication required for the cortex and cortex-compute namespaces to pull from private-registry configured to use Fabric authentication:

    note

    The Cortex CLI and kubectl must be installed and configured on the system where they are being run in order to run the auth script below.

    Execute this command to create a secret named "docker-login" for the cortex and cortex-compute namespaces.

    In Linux terminal:

    wget -O create-token-actions.sh "https://cognitivescale.github.io/cortex-charts/utilities/create-token-actions.sh" && bash ./create-token-actions.sh kubectl docker-login

    For different options for setting up Docker registry authentication go to the Private Registries page.

Upgrading to a new Fabric Version​

See the Upgrades page for release specific upgrade steps.

Next steps​

Configure logging and monitoring tools.