Cortex LogoCortex Charts
Version: 6.4.1

Installation and Configuration

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.

Recommended Prerequisites

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.

    The Fabric Helm chart's values.yaml describes the available settings and provides examples in the annotated code. Not all settings are required. Use the ones that are applicable to your deployment environment. To view the values.yaml extract the chart release and view the packaged .yaml values for the Helm release you are deploying.

    The necessary variables to override/verify in the values.yaml are

    cortex:
    # cortex.computeNamespace: the k8s namespace that Fabric custom resources are created in, default is cortex
      computeNamespace: "cortex-compute"
    # 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

  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

    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:

    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.