Install Deepfactor portal using Helm

This document outlines how to install the Deepfactor portal in your Kubernetes cluster using a Helm chart. This installation process is intended for scenarios where customization needs to be performed during the installation.

For a simpler installation process that uses default choices for most options, visit Deploying Deepfactor Portal in your Kubernetes Cluster.

Requirements #

To deploy the Deepfactor portal on Kubernetes, the following are required.

1. kubectl
2. kube config for your kubernetes cluster
3. Helm v3
4. A Kubernetes cluster with version 1.23 or later. 8vCPU and 32GB of RAM are recommended.
5. A valid Deepfactor Portal key. You can obtain the key by registering on Deepfactor’s website.
6. TLS Certificates in PEM format.

Installation #

Create deepfactor namespace #

kubectl create ns deepfactor

Generate TLS certificate #

Deepfactor allows users to generate the certificate using different methods. Please choose one of the following options based on your organization’s strategy to generate/maintain certificates.

cert-manager

Add the following section to the override.yaml

ingress:
  hostName: <your_portal_hostname>
  certManager:
    enabled: true
  cert-manager:
    enablemodule: true
    installCRDs: true

If you have already installed cert-manager in your K8s cluster, please set enablemodule: false under cert-manager section.

Self signed certificate

Download the required helper scripts from Deepfactor.

# create a directory for the files
mkdir deepfactor-certs

# change directory
cd deepfactor-certs/

wget https://static.deepfactor.io/scripts/public/df-portal/cert-gen/generate-cert.sh
wget https://static.deepfactor.io/scripts/public/df-portal/cert-gen/openssl-portal.cnf
wget https://static.deepfactor.io/scripts/public/df-portal/cert-gen/openssl-portalca.cnf

Navigate to the download directory and run the script generate-cert.sh with your preferred domain name as the argument to the script.

chmod +x generate-cert.sh
sudo ./generate-cert.sh <DNS-of-your-portal>

Create Kubernetes secret from the certificates generated by the previous step.

# create new certificates secret
kubectl -n deepfactor create secret generic df-certs-ingress \
--from-file=tls.crt=portal.crt --from-file=tls.key=portal.key \
--from-file=ca.crt=portalca.crt

AWS private CA certificate

Install Cert Manager

helm repo add jetstack https://charts.jetstack.io
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.6.1/cert-manager.crds.yaml
helm install cert-manager jetstack/cert-manager \
--namespace cert-manager \
--create-namespace \
--version v1.6.1 \
--set prometheus.enabled=false

Create an IAM OIDC provider for your cluster

https://docs.aws.amazon.com/eks/latest/userguide/enable-iam-roles-for-service-accounts.html

Create a service account for AWS PCA issuer and add helm

In the following example, pls replace the AWS zone as applicable.

eksctl create iamserviceaccount \
 --region=us-east-2 \
 --cluster=qa-test-awspca \
 --namespace=aws-pca-issuer \
 --name=aws-pca-issuer \
 --attach-policy-arn=arn:aws:iam::<Your Account ID>:policy/certificate-manager-policy \
 --override-existing-serviceaccounts --approve

Install Helm Chart For AWS PCA

helm repo add awspca https://cert-manager.github.io/aws-privateca-issuer 
helm repo update 
helm install aws-pca-issuer awspca/aws-privateca-issuer -n aws-pca-issuer \
      --set serviceAccount.create=false --set serviceAccount.name=aws-pca-issuer

Create issuer for AWS PCA

cat <<EOF | kubectl -n deepfactor apply -f -
apiVersion: awspca.cert-manager.io/v1beta1
kind: AWSPCAIssuer
metadata:
  name: df-awspcs-issuer
spec:
  arn: arn:aws:acm-pca:us-east-2:<Your Account ID>:certificate-authority/b7a66d42-65da-4970-9ebe-429988b68430
  region: us-east-2
EOF

Create certificate for the portal

Create yaml for Certificate as follows.

kind: Certificate
apiVersion: cert-manager.io/v1
metadata:
  name: app.deepfactor.io
spec:
  commonName: app.deepfactor.io
  dnsNames:
    - app.deepfactor.io
  duration: 2160h0m0s
  issuerRef:
    group: awspca.cert-manager.io
    kind: AWSPCAIssuer
    name: df-awspcs-issuer
  renewBefore: 360h0m0s
  secretName: app.deepfactor.io
  usages:
    - server auth
    - client auth
  privateKey:
    algorithm: "RSA"
    size: 2048

Use the following commands to create the certificate using the file (cert.yaml) created above

kubectl -n deepfactor apply -f cert.yaml

Check certificate status

alice@localhost:~$ kubectl -n deepfactor get certificate 
NAME                READY    SECRET                 AGE 
app.deepfactor.io   True     app.deepfactor.io      13s

Let’s Encrypt certificate

Install Cert Manager

helm repo add jetstack https://charts.jetstack.io 
helm repo update
kubectl apply -f https://github.com/jetstack/cert-manager/releases/download/v1.6.1/cert-manager.crds.yaml 
helm install \
 cert-manager jetstack/cert-manager \
 --namespace cert-manager \
 --create-namespace \
 --version v1.6.1 \
 --set prometheus.enabled=false

Create issuer for Let’s Encrypt

Create yaml file, le-issuer.yaml for Let’s Encrypt issuer as follows. Replace the highlighted configs as applicable

apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
  name: letsencrypt-issuer
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: matt@example.io
    privateKeySecretRef:
      name: letsencrypt-issuer
    solvers:
      - http01:
          ingress:
            class: df-ingress-nginx

Use the following command to create issuer for Let’s encrypt using the file (le-issuer.yaml) created above

kubectl -n deepfactor apply -f le-issuer.yaml

Create CA certificate

wget https://letsencrypt.org/certs/isrgrootx1.pem
kubectl -n deepfactor create secret generic deepfactor-certs --from-file=portalca.crt=isrgrootx1.pem

Create a certificate for the portal

Create yaml for Certificate as follows. Replace the highlighted configs as applicable

apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: dfp-letsencrypt.dmux.in
spec:
  secretName: dfp-letsencrypt.dmux.in
  dnsNames:
  - dfp-letsencrypt.dmux.in
  issuerRef:
    name: letsencrypt-issuer
    kind: Issuer
    group: cert-manager.io

Use the following commands to create a Let’s Encrypt certificate using the file (cert.yaml) created above

kubectl -n deepfactor apply -f cert.yaml

Add the Deepfactor Helm chart repo #

helm repo add deepfactor https://static.deepfactor.io/helm-charts
helm repo update

Create an override.yaml file with your config

Note: If you are using cert-manager replace app.deepfactor.io with the name of the secret created by the cert-manager issued certificate

dfstartup:
  config:
    firstName: Alice
    lastName: Smith
    emailID: alice@example.io
    ttlDays: 30
ingress:
  hostName: app.deepfactor.io
  secretName: app.deepfactor.io

Install the portal #

helm install df-stable deepfactor/deepfactor -n deepfactor \
  -f override.yaml \
  --set dfstartup.config.password=YOUR_PORTAL_PASSWORD \
  --set dfstartup.config.portalToken= \
   "YOUR_DEEPFACTOR_LICENSE_KEY_FROM_MY.DEEPFACTOR.IO"

Advanced Configuration #

The Deepfactor Helm charts support additional configurable values that can be specified in the override.yaml file.

Customizations #

We understand that different enterprises have different policies for Kubernetes clusters and hence we provide a rich set of customizations for our Deepfactor K8s portal installation. You can specify an override.yaml file while deploying our helm charts in your cluster. Some common customization scenarios are captured in the following article

Customizing your Deepfactor Portal Deployment in K8s