Install an Edge site

How to install an Edge site via the restrictive Edge CLI method

Prerequisites

• You have a global role with the Install Edge sites and the User Administration global permission, for example Edge site administrator.
• You installed Collibra Platform Self-Hosted.
• You have configured the forward proxy, if a forward proxy is required for Edge to connect to CPSH, Datadog, OpenTelemetry and jFrog. Contact your network administrator if this is applicable.
• Your server meets all system requirements.
• You must have namespace level access to the Kubernetes cluster where you want to install your Edge site.

Steps

1. Download the installer:
   1. Open a site.
      1. On the main toolbar, click → Settings.
         The Settings page opens.
      2. In the tab pane, click Edge.
         The Sites tab opens and shows a table with an overview of your sites.
      3. In the site overview, click the name of a site.
         The site page appears.
   2. Click Download Installer.

      Tip When you download the installer, an Edge user is automatically created in CPSH.

   3. Depending on your operating system and browser, follow the regular steps for downloading files.
      The installer file is a TGZ archive that contains the files proxy.properties and registries.yaml.

      Warning If you download an installer, the previously downloaded Edge site installer becomes invalid.

2. Extract the TGZ archive on the external Linux server which will be used to install the Edge site on your managed Kubernetes cluster.
   Copy

   tar -xf <edge-site-id>-installer.tgz

   Note 

   • Keep the installer or the contents of the extracted installer in a secure location on your server. These contents contain various tools that you may need later, for example to troubleshoot issues.
   • If you want to run a script or executable file from the extracted directory, ensure that the directory is not mounted as noexec. If a directory is mounted as noexec, scripts and executable files will be prevented from being run within the directory. For example, you won't be able to use the Edge CLI if you mount the directory as noexec.
3. Set the EDGE_INSTALLER_PATH environment variable to the path of the root of the extracted installer.
   Example…

   1. Go to the extracted installer and run pwd.The result should look similar to this:

      /path/to/installer/installer-111e8a59-b842-4f57-970c-32aa72000598

   2. Set the environment variable to the result:

      export EDGE_INSTALLER_PATH=/path/to/installer/installer-111e8a59-b842-4f57-970c-32aa72000598

4. Run the following command to confirm that the Kubeconfig environment variable has been set to a valid kubeconfig:
   Copy

   echo $KUBECONFIG  

5. Deploy cluster level objects:
   • Create the namespace for collibra-edge.
     Note Clusters that have more than one Edge site installed must have unique namespaces.
     How to create the namespace for collibra-edge...

     1. Copy the following command, replacing <my-namespace> with a unique name for the namespace:
        Copy

        apiVersion: v1
        kind: Namespace
        metadata:
          labels:
            pod-security.kubernetes.io/enforce: baseline
            pod-security.kubernetes.io/enforce-version: v1.27
            name: <my-namespace>

     2. Store this copied yaml into a new file called collibra-edge-ns.yaml.
     3. Create the namespace using kubectl:
        Copy

        kubectl apply -f collibra-edge-ns.yaml

     Note Throughout the remaining installation steps, replace <my-namespace> in the provided commands with this new namespace name. Example commands will have edge-namespace as an example namespace name.
   • If you are using an Openshift cluster, deploy Security Context Constraints (SCC) which provide Edge service accounts with the required permissions.
     How to create and install security constraints…

     1. Create the SCC file, for example, edge-scc-minimal.yaml, and paste the following information into it:
        Copy

        apiVersion: security.openshift.io/v1
        kind: SecurityContextConstraints
        metadata:
          name: edge-scc-documented
        allowHostDirVolumePlugin: false
        allowHostIPC: false
        allowHostNetwork: false
        allowHostPID: false
        allowHostPorts: false
        allowPrivilegeEscalation: false
        allowPrivilegedContainer: false
        allowedCapabilities: []
        allowedUnsafeSysctls: []
        defaultAddCapabilities: []
        fsGroup:
          type: MustRunAs
        priority: null
        readOnlyRootFilesystem: true
        requiredDropCapabilities: []
        runAsUser:
          type: MustRunAs
          uid: 1000
        seLinuxContext:
          type: MustRunAs
          seLinuxOptions:
            level: "s0"
            role: "system_r"
            type: "container_t"
            user: "system_u"
        seccompProfiles:
          - 'runtime/default'
        supplementalGroups:
          type: MustRunAs
        # who can use it
        users: []
        groups: [system:authenticated]

     2. Create the SCC-role file, for example, edge-scc-role-minimal.yaml, and paste the following information into it:
        Copy

        # File: edge-scc-role-minimal.yaml
        apiVersion: rbac.authorization.k8s.io/v1
        kind: Role
        metadata:
          name: edge-scc-minimal
        rules:
        - apiGroups:
          - security.openshift.io
          resourceNames:
          - edge-scc-minimal
          resources:
          - securitycontextconstraints
          verbs:
          - use
        ---
        apiVersion: rbac.authorization.k8s.io/v1
        kind: RoleBinding
        metadata:
          name: edge-scc-minimal
        subjects:
        - kind: Group
          name: system:serviceaccounts
          apiGroup: rbac.authorization.k8s.io
        roleRef:
          kind: Role
          name: edge-scc-minimal
          apiGroup: rbac.authorization.k8s.io
        

     3. Deploy both the SCC and SCC-role files:
        Copy

        kubectl apply -f edge-scc-minimal.yaml
        kubectl apply -f edge-scc-role-minimal.yaml -n <my-namespace>

   • For all cluster types, deploy priority classes:
     Copy

     kubectl apply -f resources/custom/priorityclass.yaml

6. From the Edge CLI on the machine that has the Kubernetes connection, run one of the following installation commands:
   Note 

   • You can install your Edge site with either terminal logging or terminal and file logging. Both options log the output of your Edge site installation.
     • Terminal logging only saves the output to the Edge terminal.
     • Terminal and file logging saves the output both to the terminal and a separate file. This file will be saved in the current directory with the naming format: edge-installer-$(date +"%Y-%m-%d_%H-%M-%S").log
   • With terminal logging…

     Copy

     ./edgecli install -n <my-namespace>

     Additional installation flags:

     Flag	Description
     -n <my-namespace>	If you created a custom namespace, add -n <my-namespace> to the command. For example: ./edgecli install -n <my-namespace>
     --proxy	If you are using a forward proxy, add this flag to the installation prerequisite script. Note If your proxy properties are not in the default proxy.properties file in the root of the installer, you must add the file path the installation prerequisite script. For example: --proxy temp/proxy/proxyproperties
     --ca	If you want to use a custom certificate, for example to configure a forward man-in-the-middle proxy, add this flag to the installation prerequisite script. Note If your custom certificate are not in the default ca.pem file in the root of the installer, you must add the file path the installation prerequisite script. For example: --ca temp/certs You can also use this flag to add a custom certificate for data sources. More information Your data source may require the injection of a custom certificate in order to connect with your Edge site. This custom certificate is typically signed by a private, untrusted Certificate Authority, and therefore must be added to your Edge site truststore. As you may not have a list of all required certificates at the time of installation, we recommend the ./edgecli config ca merge --path command shown in the Edge CLI topic. The process functions as follows: Edge and the data source connect using the data source certificate. Edge communicates the data source metadata to your Collibra Platform Self-Hosted using a CPSH certified certificate.
     --is-openshift	If you are using an OpenShift cluster, add this flag to deploy Security Context Constraints (SCC) which provide the Edge service accounts with the required permissions.
     --disable-otel	If you don't want to send your metrics and logs to Edge, add this flag to the installation command to disable OpenTelemetry.
     Private container image registry	Use the following flags if you want to install your Edge site with a private container image registry, which stores and manages the container images included in an Edge site installation.
     --registry-url <registry-url>	The URL of your registry. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     --registry-user <registry-user>	Your registry account username. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     --registry-pass <registry-pass>	Your registry account password. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     Private Helm registry	Use the following flags if you want to install your Edge site with a private Helm registry, which stores and manage the Helm charts included in an Edge site installation.
     --helm-url <helm-registry-url	The URL of your registry. For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --helm-user <helm-registry-user>	Your registry account username. This may look different depending on your authentication method, for example: Username Token name Service principal ID JSON key For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --helm-registry-pass <helm-pass>	Your registry account password. This may look different depending on your authentication method, for example: Password Token password Service principal secret Path to JSON file For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --user-id <user_id>	If you want to run all of your Edge site pods and containers with a specific user ID (UID), add this flag to the installation script.
     --group-id <group_id>	If you want to run all of your Edge site pods and containers with a specific group ID (GID), add this flag to the installation script.
     --unset-run-as-ids	If your Edge site is installed on an OpenShift Kubernetes cluster, and you want to run all of your Edge site pods and containers from random UIDs and GIDs, add this flag to the installation script.
     --no-priority-class-install	Warning  Don't skip priority class configuration unless you have an experienced Kubernetes engineer in your organization, as doing so may result in Edge site failures. If you need to skip installing priority classes, add this flag to the installation script. Running this flag sets all Edge site pods to the default priority (0).
     --use-custom-priority-class	Warning  Don't configure custom priority classes unless you have an experienced Kubernetes engineer in your organization, as doing so may result in Edge site failures. If you want to configure custom priority classes for your Edge site pods, add this flag, along with the following --set flags, to the installation script: --set global.priorityClassName.platform=<priority>: This flags sets the custom priority class name for Edge platform pods. This should be the highest priority class in Edge. --set global.priorityClassName.application=<priority>: This flag sets the custom priority class name for Edge application pods. This should be the second highest priority class in Edge. --set global.priorityClassName.job=<priority>:This flag sets the custom priority class name for Edge job pods. This should be the third highest priority class in Edge. Show an example --set global.priorityClassName.platform=critical-priority --set global.priorityClassName.application=high-priority --set global.priorityClassName.job=low-priority

     Show me an example…

     ./edgecli install -n edge-namespace
     --is-openshift
     --registry-url https://private-docker.registry.com 
     --registry-user user1 
     --registry-pass pass12

   • With terminal and file logging …

     Copy

     ./edgecli install -n <my-namespace> 2>&1 | tee "edge-installer-$(date +"%Y-%m-%d_%H-%M-%S").log"

     Additional installation flags:

     Flag	Description
     -n <my-namespace>	If you created a custom namespace, add -n <my-namespace> to the command. For example: ./edgecli install -n <my-namespace>
     --proxy	If you are using a forward proxy, add this flag to the installation prerequisite script. Note If your proxy properties are not in the default proxy.properties file in the root of the installer, you must add the file path the installation prerequisite script. For example: --proxy temp/proxy/proxyproperties
     --ca	If you want to use a custom certificate, for example to configure a forward man-in-the-middle proxy, add this flag to the installation prerequisite script. Note If your custom certificate are not in the default ca.pem file in the root of the installer, you must add the file path the installation prerequisite script. For example: --ca temp/certs You can also use this flag to add a custom certificate for data sources. More information Your data source may require the injection of a custom certificate in order to connect with your Edge site. This custom certificate is typically signed by a private, untrusted Certificate Authority, and therefore must be added to your Edge site truststore. As you may not have a list of all required certificates at the time of installation, we recommend the ./edgecli config ca merge --path command shown in the Edge CLI topic. The process functions as follows: Edge and the data source connect using the data source certificate. Edge communicates the data source metadata to your Collibra Platform Self-Hosted using a CPSH certified certificate.
     --is-openshift	If you are using an OpenShift cluster, add this flag to deploy Security Context Constraints (SCC) which provide the Edge service accounts with the required permissions.
     --disable-otel	If you don't want to send your metrics and logs to Edge, add this flag to the installation command to disable OpenTelemetry.
     Private container image registry	Use the following flags if you want to install your Edge site with a private container image registry, which stores and manages the container images included in an Edge site installation.
     --registry-url <registry-url>	The URL of your registry. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     --registry-user <registry-user>	Your registry account username. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     --registry-pass <registry-pass>	Your registry account password. For more information about the flags and format required for the supported registries and authentication methods, go to the private container image registry documentation.
     Private Helm registry	Use the following flags if you want to install your Edge site with a private Helm registry, which stores and manage the Helm charts included in an Edge site installation.
     --helm-url <helm-registry-url	The URL of your registry. For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --helm-user <helm-registry-user>	Your registry account username. This may look different depending on your authentication method, for example: Username Token name Service principal ID JSON key For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --helm-registry-pass <helm-pass>	Your registry account password. This may look different depending on your authentication method, for example: Password Token password Service principal secret Path to JSON file For more information about the flags and format required for the supported registries and authentication methods, go to the private Helm registry documentation.
     --user-id <user_id>	If you want to run all of your Edge site pods and containers with a specific user ID (UID), add this flag to the installation script.
     --group-id <group_id>	If you want to run all of your Edge site pods and containers with a specific group ID (GID), add this flag to the installation script.
     --unset-run-as-ids	If your Edge site is installed on an OpenShift Kubernetes cluster, and you want to run all of your Edge site pods and containers from random UIDs and GIDs, add this flag to the installation script.
     --no-priority-class-install	Warning  Don't skip priority class configuration unless you have an experienced Kubernetes engineer in your organization, as doing so may result in Edge site failures. If you need to skip installing priority classes, add this flag to the installation script. Running this flag sets all Edge site pods to the default priority (0).
     --use-custom-priority-class	Warning  Don't configure custom priority classes unless you have an experienced Kubernetes engineer in your organization, as doing so may result in Edge site failures. If you want to configure custom priority classes for your Edge site pods, add this flag, along with the following --set flags, to the installation script: --set global.priorityClassName.platform=<priority>: This flags sets the custom priority class name for Edge platform pods. This should be the highest priority class in Edge. --set global.priorityClassName.application=<priority>: This flag sets the custom priority class name for Edge application pods. This should be the second highest priority class in Edge. --set global.priorityClassName.job=<priority>:This flag sets the custom priority class name for Edge job pods. This should be the third highest priority class in Edge. Show an example --set global.priorityClassName.platform=critical-priority --set global.priorityClassName.application=high-priority --set global.priorityClassName.job=low-priority

     Show me an example…

     ./edgecli install -n edge-namespace
     --is-openshift
     --registry-url https://private-docker.registry.com 
     --registry-user user1 
     --registry-pass pass12
     2>&1 | tee "edge-installer-$(date +"%Y-%m-%d_%H-%M-%S").log"

   In the Edge sites overview, you see the status of the installation.
7. Run the following command to verify the status of the installation.
   Copy

   kubectl get pods -n <my-namespace>

Warning Collibra Support will not assist with custom Helm or Kubernetes configurations. The following steps are an example, and any assistance for configurations or issues outside of these steps is unsupported. We recommend using the Edge CLI method for managed Kubernetes installations.

A common example of custom Helm configurations is, but not limited to, using an unsupported private repository. For more information, go to our supported private helm registries documentation.

How to install an Air-gapped Edge site via the Zarf package method

Important The Zarf package method is only supported if you have an Air-gapped Collibra Platform and environment.

Prerequisites

•  In your workstation:
  • Your server meets all system requirements.
  • You must have admin level access to the Kubernetes cluster where you want to install your Edge site.
  • You have configured the forward proxy, if a forward proxy is required for Edge to connect to Collibra Platform Self-Hosted. Contact your network administrator if this is applicable.
• You must have the following in Collibra:
  • You will install your Edge site on an EKS cluster that has Zarf deployed.
    Note The AWS Load Balancer Controller is not needed.
  • The username and password for a Collibra user that has the following global permissions. This user is used only to create, reinstall, and delete Air-gapped Edge sites. For reference purposes, we will refer to this user as the Air-gapped Edge installation user.
    • Install Edge sites
    • Manage Edge sites
    • Manage connections and capabilities
    • Upload Edge charts
    • View Edge connections and capabilities

Steps

Important You can only have 1 Air-gapped Edge site per Kubernetes cluster.

1. From the Downloads page, click the latest Collibra Zarf package.
   Note If you do not see Collibra CPSH extended capabilities please reach out to your Collibra account team.
2. From the Collibra ZARF package page, click and download the Edge Zarf package.
3. Set up your kubeconfig or kubecontext so that it points to your Kubernetes cluster.
4. If you don't plan to install Technical lineage Collibra Platform Self-Hosted, apply these priority classes with kubectl apply -f cpsh-priority-classes.yaml and /cpsh-platform-zarf-package/resources/cpsh-priority-classes.yaml:
   Copy

   apiVersion: scheduling.k8s.io/v1
   kind: PriorityClass
   metadata:
     name: platform
   value: 10000000
   description: "Platform supporting services level"
   ---
   apiVersion: scheduling.k8s.io/v1
   kind: PriorityClass
   metadata:
     name: application
   value: 100000
   description: "Application level"
   ---
   apiVersion: scheduling.k8s.io/v1
   kind: PriorityClass
   metadata:
     name: job
   value: 1000
   description: "Job level"

5. Using the Zarf CLI:
   1. Copy and paste the following command in the Zarf CLI:
      Copy

      zarf package deploy <PATH TO ZST PACKAGE> \
          --set PLATFORM_ID=<DGC URL> \
          --set PLATFORM_USER=<DGC ADMIN NAME> \
          --set PLATFORM_PASSWORD=<DGC ADMIN PASSWORD> \
          --set SITE_NAME=<SITE_NAME>

      Note This can be run in interactive mode by just running the first line of the command. When you run the first line of the above command, you will be prompted to enter the information individually.
   2. Enter the relevant details for each installation flag. For example, enter your Collibra Platform Self-Hosted URL for <DGC URL>.
      Show me the Zarf flags…

      Flag	Description
      zarf package deploy <PATH TO ZST PACKAGE>	The path Edge site Zarf package you downloaded.
      --set PLATFORM_ID=<DGC URL>	The URL of your Collibra Platform Self-Hosted.
      --set PLATFORM_USER=<DGC ADMIN NAME>	The username of your Collibra admin.
      --set PLATFORM_PASSWORD=<DGC ADMIN PASSWORD>	The password of your Collibra admin.
      --set SITE_NAME=<SITE_NAME>	The desired name of your Edge site. Important  If you don't enter a site name, your Air-gapped Edge site is created with the default name: CPSH-Collibra-Edge. If you plan to have more than 1 Air-gapped Edge site on the same Collibra Platform, ensure that each site has a unique name. If you have multiple Air-gapped Edge sites with the same name on the same Collibra Platform, your sites may fail to deploy.

      Show me an example

      Copy

      zarf package deploy zarf/edgefolder \
          --set PLATFORM_ID=https://mycollibra.com \
          --set PLATFORM_USER=EdgeUser1 \
          --set PLATFORM_PASSWORD=Pass1234 \
          --set SITE_NAME=EdgeSite1234

   3. Run the command to create the Edge site.
      Your Air-gapped Edge site is created and deployed. It will appear in Edge. A dedicated user account is created in Collibra Platform Self-Hosted that grants the permission to manage your Edge site.
6. Log in to Edge to add connections and capabilities to your Air-gapped Edge site.
   Note  If an Air-gapped Edge site fails to install on your Kubernetes cluster, a site is still created in Edge. You can choose to do one of the following:

   • Remove the failed Edge site from your Kubernetes cluster and Edge by running the following command:
     Copy

     zarf package remove ZARF_PACKAGE_FILE/ZARF_PACKAGE_NAME

   • Remove the failed Edge site from your Kubernetes cluster, but keep the Edge site in Edge by running the following command:
     
     Copy

      ZARF_VAR_KEEP_CPSH_EDGE_SITE=true \
          zarf package remove ZARF_PACKAGE_FILEZARF_PACKAGE_NAME

     When you try to install or reinstall the failed Air-gapped Edge site installation, you can use the same name to reuse the Edge site in Edge.