Install Conjur Cloud Edge

This topic describes how to install a Conjur Cloud Edge.

Minimum system requirements

Each Edge must be installed on a dedicated machine.

Hardware requirements

Resource	Minimum requirement
RAM	8 GB
Hard disk	10 GB
CPU	4 cores

Software requirements

Before you begin

• Each Edge must be installed on a dedicated machine where no other applications are installed. For system requirements, see Minimum system requirements.

• Make sure you have an empty persistence folder where Edge can store configuration, log, and audit files. During Edge installation, this folder is mounted so that its files can be preserved for persistence.

• While self-signed certificates can be useful for development or proof-of-concept deployments, Edge production deployments should always use third-party certificates issued by a Trusted Root Certificate Authority. This also ensures clients can trust Edge certificates without being provided a self-signed CA certificate.

  If you choose to use a custom TLS certificate , make sure that both the certificate (.crt format) and its private key (.key format) are uploaded and that you know their location. We strongly recommend limiting access to the private key file by giving its owner read-only permissions:

  sudo chmod 400 /<Private key path>/<key>.key

  In this case, to allow Edge to access the certificate files, change the owner to the Edge user, 5000.

  Edge user	Command
  Rootful	sudo chown 5000 /<Certificate path>/<cert>.crt /<Private key path>/<key>.key
  Rootless (Podman only)	podman unshare chown 5000 /<Certificate path>/<cert>.crt /<Private key path>/<key>.key

• Make sure there is an outbound connection from the machine where you are installing Edge to Conjur Cloud. Once Edge is set up, you can work with Edge even when offline. For more information about connectivity, see Firewall traffic.

• Podman only: If the Edge user is running in rootless mode, login lingering must be enabled to allow the Conjur Cloud container to continue to run after the user is signed out.

  To enable login lingering, run:

  sudo loginctl enable-linger [user]

  In addition, do one of the following:

  • Map your port bindings to a port higher than 1024 when you run the container

  • Run the following command to allow binding to port 443:

    sudo sysctl net.ipv4.ip_unprivileged_port_start=443

• To run a podman run command in rootful mode, you might need to prefix the command with sudo before you run it.

Step 1: Download and load the Edge image

In this step, you prepare the Conjur Cloud Edge image on your Edge server:

1. Download the Edge image from the CyberArk Marketplace. The Edge container image is packaged as an archive file, conjur-edge_<version>.tar.gz.

2. After you download the image, verify that the downloaded artifact is signed by CyberArk. For more information, see Verify signed artifacts.

3. Copy the downloaded image to the machine where you want to install Edge.

4. Load the image:

   Container platform	Command
   Docker	$ docker load -i <image full path>.tar.gz
   Podman	$ podman load -i <image full path>.tar.gz

   Click to see sample output

   Getting image source signatures
   Copying blob 8cbOdc298176 done
   Copying blob f1417f83631 skipped: already exists
   Copying blob e093fb4c874 skipped: already exists
   Copying blob 5f70bf18a086 skipped: already exists
   Copying blob 04650362982 done
   Copying blob 437c46aaccdo done
   Copying blob 5f70f18a086 skipped: already exists
   Copying blob 3948476b2c91 done
   Copying config 5101448b8 done
   Writing manifest to image destination
   Storing signatures
   Loaded image: localhost/cyberark/edge: 1.0.0

Step 2: Create the Edge instance and install Edge

1. In Conjur Cloud, in the left navigation pane, click Edge.

2. Click Install new Edge.

3. On the Install Conjur Cloud Edge page, fill in the required details per the TLS certificate you are using for Edge.

   As you choose options and fill in the details, the installation script template below the details is interactively prepared for generation.

   • Custom certificate
   • Certificate auto-generated by Edge

   Elements of Edge installation script

   Element	Description
   name	The name for the Edge container; for example, edge. Allowed characters: A-Z, a-z, 0-9, underscore (_)
   CONJUR_CLOUD_URL	The URL of your Conjur Cloud service; for example, https://mysubdomain.secretsmgr.cyberark.cloud/api This value is provided by the installation script generator
   EDGE_INITIAL_CREDS	When the installation script is generated, an Edge token is automatically generated with it. The token contains the Edge user credentials. This initial token is used only when installing Edge. As soon as Edge starts running, the Edge user's API key is rotated, and this initial token becomes invalid.
   443:8443	Binds port 8443 of the container port to port 443 of Edge server
   444:8444	Binds port 8444 of the container port to port 444; used for the HTTP health endpoint. Setting this port simplifies the load balancer setup.
   mount	Binds the Edge container and the persistence folder: type=bind - Provides a simple way to share data between the Edge server and the container src=</path/to/persistence folder> - The full path you provided to the persistence folder on the Edge server, beginning with a slash (/); ; for example /etc/opt/edge dst - The path to the Edge persistence folder in the container relabel=shared - (Podman only) Ensures that the mounted files have the correct SELinux context so that they can be accessed by processes running on the Edge server U=true - (Podman only) Recursively changes the owner and group of the source volume, based on the UID and GID of the container
   -v <Certificate path> -v <Private key path>	The full paths to your custom TLS certificate (.crt) and to the certificate's private key (.key) During installation, Edge creates a volume for the two files. Edge uses these files to secure incoming communication. :z (lowercase z) - (Podman only) Modifies the label of the host file or directory being mounted into the container. This affects the file or directory on the host machine itself and can have consequences outside of the scope of container platform. This option is recommended when working with SELinux.
   restart	Docker - restart always: always restarts except when the container is stopped (manually or otherwise) Podman - restart on-failure:5: in case of failure, automatically reboots the Edge server; retries five times
   network slirp4netns:port_handler=slirp4netns	(Rootless Podman only) Provides user-mode networking for rootless users. It creates a tunnel from the host into the container to forward traffic. With slirp4netns, containers are completely isolated from each other.
   <repository>:<tag>	The Edge image repository and tag; for example, cyberark/edge:1.0.3

   Elements of Edge installation script

   Element	Description
   name	The name for the Edge container; for example, edge. Allowed characters: A-Z, a-z, 0-9, underscore (_)
   CONJUR_CLOUD_URL	The URL of your Conjur Cloud service; for example, https://mysubdomain.secretsmgr.cyberark.cloud/api This value is provided by the installation script generator
   EDGE_INITIAL_CREDS	When the installation script is generated, an Edge token is automatically generated with it. The token contains the Edge user credentials. This initial token is used only when installing Edge. As soon as Edge starts running, the Edge user's API key is rotated, and this initial token becomes invalid.
   443:8443	Binds port 8443 of the container port to port 443 of Edge server
   444:8444	Binds port 8444 of the container port to port 444; used for the HTTP health endpoint. Setting this port simplifies the load balancer setup.
   mount	Binds the Edge container and the persistence folder: type=bind - Provides a simple way to share data between the Edge server and the container src=</path/to/persistence folder> - The full path you provided to the persistence folder on the Edge server, beginning with a slash (/); ; for example /etc/opt/edge dst - The path to the Edge persistence folder in the container relabel=shared - (Podman only) Ensures that the mounted files have the correct SELinux context so that they can be accessed by processes running on the Edge server U=true - (Podman only) Recursively changes the owner and group of the source volume, based on the UID and GID of the container
   COMMON_NAME	The Edge Common Name, which is used to set the Common Name field in the TLS certificate Example: myedgedomain.com
   SAN	A comma-separated list of alternative allowed domain names (SAN) for your Edge server; makes Edge's auto-generated certificate valid to any other DNS routes that the user directs to Edge (Certificate Subject Alternative Name) Example: ec1-2-345-678-910.compute-1.amazonaws.com, myedge.com
   restart	Docker - restart always: always restarts except when the container is stopped (manually or otherwise) Podman - restart on-failure:5: in case of failure, automatically reboots the Edge server; retries five times
   network slirp4netns:port_handler=slirp4netns	(Rootless Podman only) Provides user-mode networking for rootless users. It creates a tunnel from the host into the container to forward traffic. With slirp4netns, containers are completely isolated from each other.
   <repository>:<tag>	The Edge image repository and tag; for example, cyberark/edge:1.0.3

4. Click Create Edge and generate script.

   The Edge instance is created and is added to the Edge management page.

   In addition, an installation script is generated, together with an initial Edge token.

   The generated Edge token is valid for 8 minutes, so you must run the installation script within this time.

   If you don't manage to run the script within this interval, generate the script again before you run it.

   If you closed the Install Conjur Cloud Edge page, you can generate the script from the Edge management page by clicking More options () at the end of the Edge's row.

5. Copy the script when prompted, and run it on your Edge server.

   Click to see sample output

   aca85285519cdf64ca5d8886551804ab007656c4d2f4055a40445436a5b158

6. Continue with After you install.

Step 3: After you install

After installation, verify that the container is running and that you can send an authentication request and get a secret.

1. Verify that the container is running:

   Container platform	Command
   Docker	$ docker ps -a
   Podman	$ podman ps -a

   Click to see sample output

   

2. Podman only: Create the systemd service that starts the Edge container automatically on reboot. To create this service, run the following commands:

   • Rootful
   • Rootless

   $ sudo su

   $ podman generate systemd <container-name> --name --container-prefix="" --separator="" > /etc/systemd/system/edge.service

   $ systemctl enable edge.service

   This systemd service definition includes a reference to the Edge container ID. When you recreate the container, such as after an upgrade, you must also recreate this service. To recreate the systemd service, run the following:

   $ sudo su

   $ podman generate systemd <container-name> --name --container-prefix="" --separator="" > /etc/systemd/system/edge.service

   $ systemctl daemon-reload && systemctl restart edge.service

   $ mkdir -p $HOME/.config/systemd/user

   $ podman generate systemd --name --container-prefix="" --separator="" > $HOME/.config/systemd/user/edge.service

   $ systemctl --user enable edge.service

   Enter the user password when prompted.

   This systemd service definition includes a reference to the Edge container ID. When you recreate the container, such as after an upgrade, you must also recreate this service. To recreate the systemd service, run the following:

   $ mkdir -p $HOME/.config/systemd/user

   $ podman generate systemd --name --container-prefix="" --separator="" > $HOME/.config/systemd/user/edge.service

   $ systemctl --user enable edge.service

   $ systemctl daemon-reload && systemctl restart edge.service

   Enter the user password when prompted.

3. When the container starts running, Edge starts replicating secrets from Conjur Cloud. Check the logs to see if the initial replication completed successfully. For details, see Configure log level.

   To see Edge logs, run:

   Container platform	Command
   Docker	$ docker logs -f <container_name>
   Podman	$ podman logs -f <container_name>

   If there is an issue, restart the container, or remove the container and reinstall it.

4. Try to retrieve a secret:

   1. If you are using an auto-generated, self-signed Edge certificate, you need to add this certificate to the server's trust store.

      You can trust the certificate using the instructions provided here, or using any other method that you prefer.

      • RHEL
      • Ubuntu/Debian
      • Windows
      • macOS

      Run the following commands on the endpoint server:

      1. Download the Edge certificate from the Edge server:

         openssl s_client -showcerts -connect <Edge common name>:443 </dev/null 2>/dev/null|openssl x509 -outform PEM > /tmp/conjur_edge_certificate.crt

      2. Add the certificate to the trusted store:

         sudo cp /tmp/conjur_edge_certificate.crt /etc/pki/ca-trust/source/anchors

         sudo update-ca-trust

      Run the following commands on the endpoint server:

      1. Download the Edge certificate from the Edge server:

         openssl s_client -connect <Edge common name>:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > /tmp/conjur_edge_certificate.crt

      2. Add the certificate to the trusted store:

         sudo cp /tmp/conjur_edge_certificate.crt /usr/local/share/ca-certificates

         sudo update-ca-certificates

      1. Download the Edge certificate from the Edge server using PowerShell:

         $webRequest = [Net.WebRequest]::Create("https://<Edge common name>:443")
         try { $webRequest.GetResponse() } catch {}
         $cert = $webRequest.ServicePoint.Certificate$bytes = $cert.Export([Security.Cryptography.X509Certificates.X509ContentType]::Cert)
         set-content -value $bytes -encoding byte -path "c:\conjur_edge_certificate.cer"

      2. Use Microsoft's Install certificate wizard to add the certificate to the local store. Select the following when prompted:

         • Store Location - Select Local Machine

         • Certificate store - Select Place all certificates in the following store and browse to Trusted Root Certification Authorities

      1. Download the Edge certificate from the Edge server:

         openssl s_client -connect <Edge common name>:443 -showcerts </dev/null 2>/dev/null | openssl x509 -outform PEM > /tmp/conjur_edge_certificate.crt

      2. Add the certificate to the macOS keychain. For details, see how to add certificates to your keychain using Keychain Access.

      3. Change the trust policy of the certificate to Always Trust.

   2. Authenticate the endpoint to Edge. For details, see Authenticate workloads.

   3. Check in Edge if you have execute permissions on the secret that you want retrieve. You can do this from the Conjur Cloud > Resources page, or using the Show a resource REST API.

   4. Retrieve the secret from Edge. For details, see Retrieve a secret.