Step-by-Step Solution Install with Kubernetes

These instructions are designed for those who have an existing Kubernetes environment, and detail the steps for solution install. Supported versions of Kubernetes, Helm, and Cert-Manager are listed in the Kubernetes Environments & Requirements guide. If you need more details on any step, see the Getting Started with Solutions in a Google Cloud Platform Trial Account Tutorial guide, which also provides a script that automates most of the setup.

You will need permissions to install to the Kubernetes cluster. Use of a cluster that supports dynamic PV is recommended.

To install your solution:

1. Install a supported version of Helm 3

   wget https://hclcr.io/files/sofy/scripts/get-helm3.sh && source get-helm3.sh

2. Install Cert-Manager in your cluster

   • This script can be used to perform the Cert-Manager install, or to examine the commands required: https://hclcr.io/files/sofy/scripts/cert-manager-setup.sh
   • Note: When the cluster is k8s v1.23 or newer, the minimum version of Cert-Manager is 1.8.2 and the minimum version of Helm is 3.10.x

   • How to Upgrade Cert-Manager:

     1. Untar your current solution.
     2. Navigate to the templates folder at solution/templates.
     3. Delete all the cert-manager resource files associated to the SoFy Chart, including those in the specific Product chart. (An example may be cert-ca-issuer.yaml, cert-issuer.yaml, certificate-ca.yaml, and certificate.yaml.)
     4. Next, upgrade your release with this new chart. This will cause Helm to remove the resources from step 3.
     5. Uninstall cert-manager using helm uninstall cert-manager -n cert-manager
     6. Reinstall cert manager (make sure you have jetstack in your helm repos): helm install cert-manager jetstack/cert-manager --namespace cert-manager --create-namespace --version v1.8.2 --set installCRDs=true
     7. Download your upgraded solution.
     8. Upgrade helm release using the new solution.
     9. Verify if your certificates are working as expected.

3. Installation of Emissary Ingress Custom Resource Definitions (CRDs)

   • The below commands install Emissary-ingress CRDs in the emissary-system namespace
   • Commands to install CRDs:

   kubectl apply -f https://app.getambassador.io/yaml/emissary/2.2.2/emissary-crds.yaml

   kubectl wait --timeout=90s --for=condition=available deployment emissary-apiext -n emissary-system

4. Create a namespace for your solution (optional)

   • Each solution must be installed in a separate namespace; if you install into the default namespace you can omit the --namespace parameters on the remaining commands

   kubectl create namespace [name]

5. Create an image pull secret in the solution namespace

   kubectl create secret docker-registry [secret-name] --docker-server=hclcr.io --docker-username=[sofy userid] --docker-password=[CLI secret] --namespace=[solution namespace]

   • To set your Harbor CLI secret, login to the container registry at hclcr.io with your HCL/SoFy credentials, selecting LOGIN VIA OIDC PROVIDER. To get access to the container registry, please see Accessing SoFy.
   • Open your User Profile (in the top right corner, click on the dropdown for your username) and enter a secret string of your choice
   • Use this string as the CLI secret in the command shown above

6. Use Helm to install the solution chart

   • The solution chart can be downloaded from the SoFy application, on the Catalog Details screen

   helm install [release-name] [file-name] --namespace [solution-namespace] --set global.hclImagePullSecret=[secret-name] --set hclFlexnetURL=[flexnet-url] --set hclFlexnetID=[flexnet-id]

7. Summary of the variables above:

   • [release-name] A Helm release name that is not already used
   • [file-name] The file name of your downloaded solution
   • [solution-namespace] The namespace you are installing your solution into
   • [secret-name] The name of your pull secret created in Step #4
   • [flexnet-url], [flexnet-id] Your license server information. For more information about these fields see the Connect to Flexnet. Note: If you do not specify these values, some solution contents may not initialize properly or have full function available until you enter your license server information via the SoFy Console Settings

8. You may need to set additional value overrides for the specific contents of your solution, see the documentation for those products and services in the SoFy Catalog.

9. Default value for solutions generated in HCL SoFy is:

   --set global.hclImageRegistry="hclcr.io/sofy"

10. That can be overridden to point to another registry (if you are hosting images locally), for example:

    --set global.hclImageRegistry=registry.io/project

11. If you are using an AWS EKS cluster, add the below annotation to the solution's Ambassador or Emissary service so it can receive an external IP:

    kubectl annotate svc [solution-ambassador-or-emissary-svc] -n [solution-namespace] service.beta.kubernetes.io/aws-load-balancer-internal=0.0.0.0/0

12. Note: The process of assigning an external LoadBalancer IP address to the annotated service may take a few minutes.

    kubectl get cm [releasename]-domain -o yaml

    The output will be similar to the following. You will need the value of the HOST field:

    apiVersion: v1 
    data: 
        HOST: 10.190.16.62.nip.io
        HOST_PROTOCOL: https 
    kind: ConfigMap
    

13. Access the SoFy Console

    • Once the install has completed and all pods are ready, enter the HOST into this link to access the SoFy Console app in your browser: https://sofy-console.${HOST}.

    • You will see some warnings about the certificate used in the solution; it is safe to accept these and proceed to the SoFy Console application.

    • Log in to the application using the initial password for the 'sol-admin' user that is generated at solution install, and stored in a Kubernetes secret with the name:

      {{ .Release.Namespace }} {{ .Release.Name }}-acs-default-credentials.

    • For example, if you installed your solution using the release name 'gcp1' into the default namespace, you would view the password using the below command line:

      kubectl get secret gcp1-acs-default-credentials -o json | jq -r ".data.admin" | base64 --decode ; echo

    • The SoFy Console provides information about all parts of the solution, as well as links to the home pages of the included products and services.

    • The GCP Trial Install guide provides detail on viewing the status of the install process and various troubleshooting tips.