Setting up the Private Distribution Network
Once you have completed the installation of the PDN Server and PDN Node. you are ready to set up your PDN.
The basic process of setting up the PDN Nodes comprises these main steps:
- Download the JFrog PDN Server and customize the basic PDN Node YAML file.
Configure the PDN Node as an HTTP/HTTPS Proxy.
Step 1: Establish Trust between the JFrog Platform Deployment (JPD) and PDN Nodes
To create trust between the JFrog Platform Deployment (JPD) and a PDN Node, the PDN Node can use any of the following authentication methods:
- Token-based API authentication.
- Mutual TLS (mTLS) Authentication.
Authentication is specified in the PDN Node configuration YAML file.
Token-based API Authentication
There are two methods for authenticating using a token:
- To use a token-based API key authentication, configure the
joinKey
attribute in your customized PDN Node YAML file.
- To generate an API key (an Access Token)
- In the JFrog Platform, go to Admin | User Management | Settings | PDN Access Token., generate and copy the key.
- To view the join key, click the Show join key icon.
- In the JFrog Platform, go to Admin | User Management | Settings | PDN Access Token., generate and copy the key.
Mutual TLS Authentication
To use Mutual TLS Authentication configure pdnnode.PEMFilePath
attribute to specify the path to the local .pem file that contains the certificate for SSL client authentication and the client certificate key.
By default, PDN Node uses the list of trusted certificate authorities (CA) from the operating system where it is running.
If the certificate authority that signed your certificates is not in the host system’s trusted certificate authorities list, you need to add the path to the file that contains your CA’s certificate by defining the pdnnode.certificatAuthorityPath
attribute.
Step 2: Customize the PDN
Establishing Connectivity between the PDN Nodes
Upon startup, the PDN Nodes need to establish connectivity with the other PDN Nodes through a secure gRPC connection by applying an access root certificate. The PDN Node can retrieve this certificate using one of the following:
- Using mTLS Authentication (see above)
- A digital envelope through an insecure connection.
- A certificate located on the PDN local machine by setting the
pdnnode.accessRootCertificate
attribute.
- Choose your PDN Node installation.
Customize a PDN file with the Static Node Attributes yaml file for the basic static attributes including addresses, ports, certificates, and directories.
Using Environment Variables
You can also configure the PDN Application using the environment variables starting with the JF_PDNNODE prefix.
Deploy the YAML with the Static attributes and run the JFrog PDN Application on all of the PDN Nodes.
When the PDN Nodes initially connect to the PDN Server, they will automatically be populated with the default PDN Nodes configurations that are centrally stored in the JFrog Platform. These configurations are updated dynamically every time the PDN Nodes connect to the PDN Server and can be modified using the REST API, directly in the UI, or through the bootstrap from the file system.
To modify the dynamic node attributes, see Advanced Private Distribution Network (PDN) Configurations.
Step 3: Configure the PDN Node as an HTTP/HTTPS Proxy
To provide you with a seamless experience when working opposite Artifactory via the PDN Node, you need to set the PDN Node as an HTTP/HTTS Proxy. After you have set up the PDN Node as a proxy, all the requests sent from the Docker client will be routed through the PDN Node. For more information, see Getting Started with Artifactory.
Set the location on your PDN to the following path.
$JF_PRODUCT_HOME=[path on your machine]
Copy your customized PDN Node
system.yaml
to the following path.$JF_PRODUCT_HOME/var/etc/system.yaml
Run the PDN Node with your preferred installation.
Copy the certificates with a
.crt
extension located under$JF_PRODUCT_HOME/var/etc/security/certificates
to the folder in which your operating system runs the Docker Daemon.
For example, Alpine users can copy their files to the following location in which the Docker Daemon has been designated to run the files.apk add ca-certificates cp ./certificates/jfrog_proxy.crt /usr/local/share/ca-certificates/jfrog_proxy.crt cp ./certificates/jfrog_access_root.crt /usr/local/share/ca-certificates/jfrog_access_root.crt update-ca-certificates
Start the Docker Daemon with an HTTP proxy pointing to the PDN Node self HTTP address.
As displayed in the following example, you can run the Docker Daemon directly.HTTPS_PROXY=selfHttpAddress dockerd
Step 4: Configure Nginx to Support Load Balancing Between PDN Nodes.
Load Balancing allows you to set up your PDN in a way that provides high availability with high performance, which is critical for service quality, with minimal configuration.
PDN retrieves files by accessing a specific PDN Node in a specific PDN Group according to the group's IP address. Because each PDN Node in each group is dynamic, meaning a PDN Node can be shut down or started at any time, it is more efficient to work with a small subset of PDN Node IPs rather than managing them all. This can be achieved by configuring the Nginx configuration template with all the active PDN Nodes in a group, thus improving the high availability and reducing the management of PDN Nodes IPs. The PDN Nodes within the same group will balance the load of incoming requests between each other, while continuously synching the cache for optimal performance.
Configuration Steps
Follow the steps below to configure an Nginx node.
Run the following REST API request.
GET /api/v1/template
The configuration retrieved will include the IP addresses of all the PDN Nodes in the group. The HTTP port will be different from the direct communication port, as this new port will expose the PDN Node with a load balancing functionality.
upstream backend { server node1:8090; server node2:8090; server node3:8090; } server { location / { proxy_pass http://backend } }
- Create a new configuration file under
/etc/nginx/conf.d
with the file ending*.conf
. - Use the output generated by the REST API request and set the Nginx server as a reverse proxy to the PDN Nodes.
Make sure to use the exact output content, and verify that there are no other configuration files that might affect this configuration. Note that the default .conf
file that also configures the reverse proxy settings must be removed or modified.
Advanced Setup
Working with Docker Strategies
To support the different Docker resolution strategies, you will need to apply the following PDN Node rewrite mechanism. For more information, see Using a Reverse Proxy. The following examples illustrate the supported strategies.
Supported Strategies
Repository Path Mapping
This is the default configuration supported by the PDN Node. The repository path method allows a single point of entry (URL) to access different repositories. This is done by embedding the name of the repository being accessed into the image path.
If you want to add support for resolving Docker images without specifying a repository path, follow the rewrite rules as displayed.
pdnnode: rewrite: - from: https://registry-1.docker.io/v2/library/(.*) to: https://<myarticatory.com>/v2/<default Docker repository>/$1
Subdomain Mapping
To support subdomain mapping, configure the rewrite tool based on your configuration. For example, if you are using the Nginx configuration used in Artifactory, follow these rewrite rules.
pdnnode: rewrite: - from: https://(.*).<myartifactory.com>/(.*) to: https://<myartifactory.com>/artifactory/api/docker/$1/$2
Port Mapping
To support port mapping, you will have to map the port to the required repository by following these rewrite rules.
pdnnode: rewrite: - from: https://<myartifactory.com>:<port1>/(.*) to: https://<myartifactory.com>/artifactory/api/docker/<repokey1>/$1 //repokey relates to the port we want to map to this key - from: https://myartifactory.com:<port2>/(.*) to: https://myartifactory.com/artifactory/api/docker/<repokey2>/$1 //repokey relates to the port we want to map to this key - from: https://myartifactory.com:<port3>/(.*) to: https://myartifactory.com/artifactory/api/docker/<repokey3>/$1 //repokey relates to the port we want to map to this key
Downloading Files from the PDN Node Using Docker Client
Validate that you have a Docker repository in Artifactory.
Running Docker commands in the Docker client through the PDN Node is the same as running Docker commands opposite Artifactory. Your permissions and credentials for downloading files are identical to your permissions in Artifactory and are retrieved when performing actions opposite the PDN Node.
Docker Login Request Examples
For the Docker client to connect to the PDN Node and download through this nod, you will need to run docker login to the PDN Node.
Note that HOST_IP
refers to your machine's IP address.
To run a Docker login command using the repository path:
$ docker login --username admin --password password1 <artifactory_URL>
Example: Docker Login using the repository path$ docker login --username admin --password password1 myartifactory.com
To run a Docker login command using using the subdomain:
$ docker login --username admin --password password1 <repokey>.<artifactory_URL>
Example: Docker Login using the subdomain$ docker login --username admin --password password1 docker-local.myartifactory.com
To run a Docker login command using the port:
$ docker login --username admin --password password1 <artifactory_URL>:<port>
Example: Docker login using the port$ docker login --username admin --password password1 myartifactory.com:9922
Docker Pull Request Examples
Running a Docker Pull command using the repository path.
$ docker pull <artifactory_URL>/<repokey>/<image_name>:<version>
$ docker pull myartifactory.com/docker-local/mysql:latest
Running a Docker Pull command using the subdomain.
$ docker pull <repokey>.<artifactory_URL>/<image_name>:<version>
$ docker pull docker-local.myartifactory.com/mysql:latest
Running a Docker Pull command using the port.
$ docker pull <artifactory_URL:port>/<image_name>:<version>
docker pull myartifactory.com:9922/mysql:latest
Docker Push Request Example
Running a Docker Push command using the repository path.
$ docker push <artifactory_URL>/<repokey>/<image_name>:<version>
$ docker push myartifactory.com/docker-local/mysql:latest
Next: Working with the Private Distribution Network (PDN) >>
Optional: Advanced Private Distribution Network (PDN) Configurations >>