Install Tangram Pro™

---

Deploying Tangram Pro™

Now that you have your supporting software installed and necessary assets collected, you're ready to install the Tangram Pro™ Helm chart.

note

For a full list of the values available in the chart for your deployment please refer to the Tangram Pro™ Chart Values.

Prerequisites

Before you Install

Before install, you will need these items which will be provided by Tangram Flex:

• Your license public key
• Your license private key
• Your license private key password
• Your custom values file

Contact your Tangram customer support contact for more details.

Install Directory

Below is the recommended directory structure. Tangram Flex will provide these files to you as part of the deployment package.

.
└── tangram_pro
    ├── bash_commands.scratch
    ├── ingress
    │   └── ingress_nginx_values.yaml
    ├── license
    │   ├── customer.key
    │   ├── customer.tflicense
    │   ├── license-secret.yaml
    │   ├── pk_pass
    │   └── tangram.pub
    ├── tangram_pro_values.yaml
    ├── tls
    │   ├── cert-manager
    │   │   └── cert_manager_values.yaml
    │   └── manual
    │       ├── certificate-secret.yaml
    │       ├── certificate.key
    │       └── certificate.pem
    └── variables.env

More Info about the files

File	Description
bash_commands.scratch	This file has most of the common commands you may use for your deployment. Use it is a starting point to deploy prerequisites, common Kubernetes objects, and to build your Tangram Pro™ helm installation command.
ingress/ingress_nginx_values.yaml	Standard configuration Helm values overrides file for Ingress NGINX Controller
license/customer.key	This file is used for decryption and provided by Tangram Flex as part of the deployment package.
license/customer.tflicense	This is the encrypted license file provided by Tangram Flex as part of the deployment package.
license/license-secret.yaml	This is a pre-generated secret file provided by Tangram Flex as part of the deployment package.
license/pk_pass	This file is used for decryption and provided by Tangram Flex as part of the deployment package.
license/tangram.pub	This file is used for decryption and provided by Tangram Flex as part of the deployment package.
tangram_pro_values.yaml	This is a starting point for a Helm values overrides file for deploying Tangram Pro™ See: Helm Values for all possible configuration
tls/cert-manager/cert_manager_values.yaml	Standard configuration Helm values overrides file for Cert Manager
tls/manual/certificate-secret.yaml	A placeholder file for your pregenerated Kubernetes tls secret
tls/manual/certificate.key	Placeholder for your Certificate Private Key (not password protected), in PEM encoded base64 format
tls/manual/certificate.pem	Placeholder for your Certificate, in PEM encoded base64 format
variables.env	A Bash sourceable file to set Environment variiables and other variables and/or functions

Install Tangram Pro™:

1. Prepare your session:

   export TANGRAM_PRO_NAMESPACE="tangram-pro"
   export TANGRAM_PRO_RELEASE_NAME="tangram-pro"
   export TANGRAM_PRO_SUBDOMAIN="pro" # The sub-domain for the URL you are deplpoying for access to Tangram Pro™, used with the ingress controller.
   export TANGRAM_PRO_DOMAIN="domain.com" # The domain for the URL you are deplpoying for access to Tangram Pro™, used with the ingress controller.
   export TANGRAM_PRO_VALUES_FILE="tangram_pro_values.yaml" # Path to the values override file you want to use.
   

   or if you are using a variables.env file

   source variables.env
   

2. Add the Tangram Pro™ chart repo to helm and update it.

   helm repo add tangram https://charts.tangramflex.io
   helm repo update
   

3. Create the Tangram Pro™ namespace

   kubectl create ns "$TANGRAM_PRO_NAMESPACE"
   

4. (Optional) Create Kubernetes objects prior to install
   Manual Certificates

   If you are not using Cert Manager you have options to use your own Certificate(s), possibly issued by a private Certificate Authority, trusted by your system(s).

   See Manual Certificates for information about file requirements.

   To create a Kubernetes TLS secret run the following command:

   export MANUAL_CERT_DIR='.' # Root directoy where manual certificates and the secret will be located, 
   export MANUAL_CERT_PRIVATE_KEY_FILE="${MANUAL_CERT_DIR}/local_tangramflex_net.key" # tls/manual/certificate.key
   export MANUAL_CERT_FILE="${MANUAL_CERT_DIR}/local_tangramflex_net.crt" # tls/manual/certificate.pem
   export MANUAL_CERT_SECRET_FILE="${MANUAL_CERT_DIR}/certificate_secret.yaml" # The TLS secret yaml file 
   export MANUAL_CERT_SECRET_NAME="tangram-pro-tls" # Name of the secret in Kubernetes
   
   kubectl create secret tls "$MANUAL_CERT_SECRET_NAME" \
   -n "$TANGRAM_PRO_NAMESPACE" \
   --key="${MANUAL_CERT_PRIVATE_KEY_FILE}" \
   --cert="${MANUAL_CERT_FILE}"
   

   note

   If you would like to output the secret to a yaml file to maintain in CI or Some other reason add this to the end of the command.

   --dry-run=client -o yaml > "${MANUAL_CERT_SECRET_FILE}"
   

   And then set this value in your values file.

   tls:
     existingSecret: tangram-pro-tls # Should be the same value set to variable 'MANUAL_CERT_SECRET_NAME'
   

   License Secret(s)

   Licensing consists of two components, decryption files, and the encrypted license file.

   If you would like to pre-create Kubernetes secrets for licensing.

   Decryption Secret

   To create the Kubernetes secret object for the decryption files run the following command:

   export TANGRAM_PUB_FILE="license/tangram.pub" 
   export CUSTOMER_KEY_FILE="license/customer.key"
   export CUSTOMER_KEY_PASS_FILE="license/pk_pass"
   export LICENSE_DECRYPT_SECRET_NAME="license-decrypt"
   
   kubectl create secret generic "$LICENSE_DECRYPT_SECRET_NAME" -n "$TANGRAM_PRO_NAMESPACE" \
   --from-file=tangram_id_rsa.pub="$TANGRAM_PUB_FILE" \
   --from-file=id_rsa="$CUSTOMER_KEY_FILE" \
   --from-literal=LICENSE_PRIVATE_KEY_PASS="$(cat "$CUSTOMER_KEY_PASS_FILE" | base64 -d)"
   

   And then set this value in your values file.

   license:
     existingSecret: license-decrypt # This should match the value set in the variable 'LICENSE_DECRYPT_SECRET_NAME'
   

   License Secret

   If you would like to create the encrypted license secret run the following command.

   export LICENSE_FILE="license/customer.tflicense" # Path to the '.tflicense' file, i.e., license/customer.tflicense
   export LICENSE_SECRET_NAME="backend-license"
   
   kubectl create secret generic "$LICENSE_SECRET_NAME" -n "$TANGRAM_PRO_NAMESPACE" \
   --from-file=license.tflicense="$LICENSE_FILE"
   

   And then set this value in your values file.

   backend:
     license:
       enabled: true
       existingSecret: backend-license # This should be the same value set in the variable 
   

   Registry Secret(s)

   Kubernetes pulls the conatiner images from an OCI(Docker) registry.

   You can pre-create a Kubernetes secret for the OCI image registry pull secret and reference it in your values overrides file.

   To create the Kubernetes OCI registry secret object run the following command:

   export REGISTRY_SECRET_NAME="gitlab-pro-registry" # name you would like for the secret 
   export REGISTRY_SERVER_URL="registry-gitlab.tangramflex.io" # URL of your OCI registry
   export REGISTRY_USERNAME="registry_username_providedby_tangram_flex" # username for your regsitry
   export REGISTRY_PASSWORD="password_from_tangram_flex" # password for your regsitry
   
   kubectl create secret docker-registry $REGISTRY_SECRET_NAME \
   --docker-server="$REGISTRY_SERVER_URL" \
   --docker-username="$REGISTRY_USERNAME" \
   --docker-password="${$REGISTRY_PASSWORD}" \
   --namespace="$TANGRAM_PRO_NAMESPACE"
   

   And then set this value in your values file.

   global:
     imageRegistry: registry-gitlab.tangramflex.io # This should match the value set in the variable 'REGISTRY_SERVER_URL'
     imagePullSecrets:
     - gitlab-pro-registry # This should match the value set in the variable 'REGISTRY_SECRET_NAME'
   registry:
     existingSecret: gitlab-pro-registry # This should match the value set in the variable 'REGISTRY_SECRET_NAME'
   

5. Build your helm command.

   This is the base helm command and can be used as-is if you pre-create necessary secrets (See Manual Certificates above).

   helm upgrade "$TANGRAM_PRO_RELEASE_NAME" -n "$TANGRAM_PRO_NAMESPACE" tangram/pro \
   --install \
   --wait --timeout 10m \
   -f "$TANGRAM_PRO_VALUES_FILE" \
   --set subdomain="$TANGRAM_PRO_SUBDOMAIN" \
   --set domain="$TANGRAM_PRO_DOMAIN"
   

   1. (Required) Configure Docker Registry Auth...

      Docker Registry needs to authenticate to the backend service. You two options...

      • Provide the configuration in the Helm command

         \
        --set docker-registry.configData.auth.token.realm="https://${TANGRAM_PRO_SUBDOMAIN}.${TANGRAM_PRO_DOMAIN}/api/v2/registry/auth" \
        --set docker-registry.configData.auth.token.service="${TANGRAM_PRO_SUBDOMAIN}.${TANGRAM_PRO_DOMAIN}" \
        --set docker-registry.configData.auth.token.issuer="${TANGRAM_PRO_SUBDOMAIN}.${TANGRAM_PRO_DOMAIN}"
        

      • Add the configuration to the values override file

        docker-registry:
          configData:
            auth:
              token:
                # {{DOMAIN}} should be equivalent to .Values.subdomain + "." + .Values.domain
                realm: "https://{{DOMAIN}}/api/v2/registry/auth"
                service: "{{DOMAIN}}"
                issuer: "{{DOMAIN}}"
        

   2. (Required) Provide License files and info...

      If you want to provide the License requirements at install and upgrade time, rather than using an existing secret and the values overrides file (See License Secret(s) in number 4 above), append this to your command...

      License Decryption

       \
      --set license.privateKeyPass="<passwordProvidedByTangram>" \
      --set-file license.publicKeyFile="<path/to/license/public_key.pub>" \
      --set-file license.privateKeyFile="<path/to/license/private_key.key>"
      

      or if you want to use the a secret previsouly created and added to the namespace yet provide the secret value in the Helm install command rather than add it to the values file.

       \
      --set license.existingSecret="$LICENSE_DECRYPT_SECRET_NAME"
      

      Encrypted license file

      If you would like to provide the Encrypted license information at Helm Install rather than applying it in the GUI you can add

       \
      --set backend.license.enabled="true" \
      --set backend.license.content="$(cat $LICENSE_FILE)"
      

      or if you opted to create the encrypted license file secret

       \
      --set backend.license.enabled="true" \
      --set backend.license.existingSecret="$LICENSE_SECRET_NAME"
      

   3. (Required) Provide Image Registry secret info...

      If you want to provide the Image Registry information at install and upgrade time, rather than using an existing secret and the values overrides file (See Registry Secret(s) in number 4 above), append this to your command...

      • Using the default image registry with a Tangram Flex provided username and password

         \
        --set registry.username="<usernameProvidedByTangram>" \
        --set registry.password="<passwordProvidedByTangram>"
        

      • Using some other registry

         \
        --set global.imageRegistry="<urlOfOtherRegistry>" \
        --set registry.username="<usernameOfOtherRegistry>" \
        --set registry.password="<passwordOfOtherRegistry>"
        

        note

        The name of the default registry secret is gitlab-pro-registry. If you want to use a different secret name you can pre-create the secret and reference it (see below).

        or if you want to use the a secret previsouly created and added to the namespace yet provide the secret value in the Helm install command rather than add it to the values file.

         \
        --set global.imageRegistry="$REGISTRY_SERVER_URL" \
        --set global.imagePullSecrets={"$REGISTRY_SECRET_NAME"} \
        --set registry.existingSecret="$REGISTRY_SECRET_NAME"
        

        note

        When using an existing secret and setting the global.imagePullSecrets value, be aware that the value is a list and in Helm, when using --set, has limitations.

   Certificates: If you are not using cert-manager and wish to provide the TLS certificate and key at installation...

   certificate variables

   For the certificate file path variables see the Manual Certificates guide.

    \
   --set-file tls.certFile="${MANUAL_CERT_FILE}" \
   --set-file tls.keyFile="${MANUAL_CERT_PRIVATE_KEY_FILE}"
   

   or

   If you

    \
   --set tls.existingSecret="$MANUAL_CERT_SECRET_NAME"
   

   Metrics: By default Metrics are enabled. If you need to disable...

   If you want to disable metrics you have two options:

   • Add the following to your Helm command.

      \
     --set metricsEnabled=false \
     --set gitea.gitea.metrics.enabled=false \
     --set gitea.gitea.metrics.serviceMonitor.enabled=false
     

   • Set the following values in your values override file.

     metricsEnabled: false
     gitea:
       gitea:
         metrics:
           enabled: false
           serviceMonitor:
             enabled: false
     

You can watch the installation progress via kubectl get pods -n $tangram to view the status of the pods created by the installation.

Configure DNS

• Depending on your cluster configuration, you may need to manually create DNS records to allow traffic to your Tangram Pro™ instance. If your ingress solution automatically provisions a load balancer, as with AWS ELBs for instance, you can obtain the hostname:

kubectl get ingress frontend -n $tangram -o=jsonpath="{.status.loadBalancer.ingress[0].hostname}"

• Using your domain provider, create a CNAME record for your designated domain with a value set to the result from the above command.