rancher-partner-charts/charts/artifactory-ha

JFrog Artifactory High Availability Helm Chart

Heads up: Our Helm Chart docs are moving to our main documentation site. For Artifactory installers, see Installing Artifactory.

Prerequisites Details

• Kubernetes 1.12+
• Artifactory HA license

Chart Details

This chart will do the following:

• Deploy Artifactory highly available cluster. 1 primary node and 2 member nodes.
• Deploy a PostgreSQL database NOTE: For production grade installations it is recommended to use an external PostgreSQL
• Deploy an Nginx server

Artifactory HA architecture

The Artifactory HA cluster in this chart is made up of

• A single primary node
• Two member nodes, which can be resized at will

Load balancing is done to the member nodes only. This leaves the primary node free to handle jobs and tasks and not be interrupted by inbound traffic. This can be controlled by the parameter artifactory.service.pool. NOTE: Using artifactory pro license (which supports single node only), set artifactory.node.replicaCount=0 in values.yaml. To scale from single node to multiple nodes(>1), use Enterprise(+) license and then do an helm upgrade (Each node need a seperate license).

Installing the Chart

Add ChartCenter Helm repository

Before installing JFrog helm charts, you need to add the ChartCenter helm repository to your helm client

helm repo add center https://repo.chartcenter.io
helm repo update

NOTE: Passing masterKey is mandatory for fresh install of chart (7.x Appversion)

Create a unique Master Key

Artifactory HA cluster requires a unique master key.

For production grade installations it is strongly recommended to use a custom master key. If you initially use the default master key it will be very hard to change the master key at a later stage

You should generate a unique one and pass it to the template at install/upgrade time.

# Create a key
export MASTER_KEY=$(openssl rand -hex 32)
echo ${MASTER_KEY}

Install Chart

To install the chart with the release name artifactory-ha:

helm upgrade --install artifactory-ha --set artifactory.masterKey=${MASTER_KEY} --namespace artifactory-ha center/jfrog/artifactory-ha

System Configuration

Artifactory uses a common system configuration file - system.yaml. See official documentation on its usage. In order to override the default system.yaml configuration, do the following:

artifactory:
  systemYaml: |
    <YOUR_SYSTEM_YAML_CONFIGURATION>

Deploying Artifactory for small/medium/large installations

In the chart directory, we have added three values files, one for each installation type - small/medium/large. These values files are recommendations for setting resources requests and limits for your installation. The values are derived from the following documentation. You can find them in the corresponding chart directory - values-small.yaml, values-medium.yaml and values-large.yaml

Accessing Artifactory

NOTE: It might take a few minutes for Artifactory's public IP to become available, and the nodes to complete initial setup. Follow the instructions outputted by the install command to get the Artifactory IP and URL to access it.

Updating Artifactory

Once you have a new chart version, you can update your deployment with

helm upgrade artifactory-ha --namespace artifactory-ha center/jfrog/artifactory-ha

If artifactory was installed without providing a value to postgresql.postgresqlPassword (a password was autogenerated), follow these instructions:

1. Get the current password by running:

POSTGRES_PASSWORD=$(kubectl get secret -n <namespace> <myrelease>-postgresql -o jsonpath="{.data.postgresql-password}" | base64 --decode)

2. Upgrade the release by passing the previously auto-generated secret:

helm upgrade <myrelease> --namespace artifactory-ha center/jfrog/artifactory-ha --set postgresql.postgresqlPassword=${POSTGRES_PASSWORD}

This will apply any configuration changes on your existing deployment.

Special Upgrade Notes

Artifactory upgrade from 6.x to 7.x (App Version)

Arifactory 6.x to 7.x upgrade requires a one time migration process. This is done automatically on pod startup if needed. It's possible to configure the migration timeout with the following configuration in extreme cases. The provided default should be more than enough for completion of the migration.

artifactory:
  # Migration support from 6.x to 7.x
  migration:
    enabled: true
    timeoutSeconds: 3600

• Note: If you are upgrading from 1.x to 4.x and above chart versions, please delete the existing statefulset of postgresql before upgrading the chart due to breaking changes in postgresql subchart.

kubectl delete statefulsets <OLD_RELEASE_NAME>-postgresql

Artifactory memory and CPU resources

The Artifactory HA Helm chart comes with support for configured resource requests and limits to all pods. By default, these settings are commented out. It is highly recommended to set these so you have full control of the allocated resources and limits.

See more information on setting resources for your Artifactory based on planned usage.

# Example of setting resource requests and limits to all pods (including passing java memory settings to Artifactory)
helm upgrade --install artifactory-ha \
               --set artifactory.primary.resources.requests.cpu="500m" \
               --set artifactory.primary.resources.limits.cpu="2" \
               --set artifactory.primary.resources.requests.memory="1Gi" \
               --set artifactory.primary.resources.limits.memory="4Gi" \
               --set artifactory.primary.javaOpts.xms="1g" \
               --set artifactory.primary.javaOpts.xmx="4g" \
               --set artifactory.node.resources.requests.cpu="500m" \
               --set artifactory.node.resources.limits.cpu="2" \
               --set artifactory.node.resources.requests.memory="1Gi" \
               --set artifactory.node.resources.limits.memory="4Gi" \
               --set artifactory.node.javaOpts.xms="1g" \
               --set artifactory.node.javaOpts.xmx="4g" \
               --set initContainers.resources.requests.cpu="10m" \
               --set initContainers.resources.limits.cpu="250m" \
               --set initContainers.resources.requests.memory="64Mi" \
               --set initContainers.resources.limits.memory="128Mi" \
               --set postgresql.resources.requests.cpu="200m" \
               --set postgresql.resources.limits.cpu="1" \
               --set postgresql.resources.requests.memory="500Mi" \
               --set postgresql.resources.limits.memory="1Gi" \
               --set nginx.resources.requests.cpu="100m" \
               --set nginx.resources.limits.cpu="250m" \
               --set nginx.resources.requests.memory="250Mi" \
               --set nginx.resources.limits.memory="500Mi" \
               --namespace artifactory-ha center/jfrog/artifactory-ha

Artifactory java memory parameters can (and should) also be set to match the allocated resources with artifactory.[primary|node].javaOpts.xms and artifactory.[primary|node].javaOpts.xmx.

Get more details on configuring Artifactory in the official documentation.

Although it is possible to set resources limits and requests this way, it is recommended to use the pre-built values files for small, medium and large installation and change them according to your needs (if necessary), as described here

Deploying Artifactory for small/medium/large installations

In the chart directory, we have added three values files, one for each installation type - small/medium/large. These values files are recommendations for setting resources requests and limits for your installation. The values are derived from the following documentation. You can find them in the corresponding chart directory - values-small.yaml, values-medium.yaml and values-large.yaml

Artifactory storage

Artifactory HA support a wide range of storage back ends. You can see more details on Artifactory HA storage options

In this chart, you set the type of storage you want with artifactory.persistence.type and pass the required configuration settings. The default storage in this chart is the file-system replication, where the data is replicated to all nodes.

IMPORTANT: All storage configurations (except NFS) come with a default artifactory.persistence.redundancy parameter. This is used to set how many replicas of a binary should be stored in the cluster's nodes. Once this value is set on initial deployment, you can not update it using helm. It is recommended to set this to a number greater than half of your cluster's size, and never scale your cluster down to a size smaller than this number.

Existing volume claim

Primary node

In order to use an existing volume claim for the Artifactory primary storage, you need to:

• Create a persistent volume claim by the name volume-<release-name>-artifactory-ha-primary-0 e.g volume-myrelease-artifactory-ha-primary-0
• Pass a parameter to helm install and helm upgrade

...
--set artifactory.primary.persistence.existingClaim=true

Member nodes

In order to use an existing volume claim for the Artifactory member nodes storage, you need to:

• Create persistent volume claims according to the number of replicas defined at artifactory.node.replicaCount by the names volume-<release-name>-artifactory-ha-member-<ordinal-number>, e.g volume-myrelease-artifactory-ha-member-0 and volume-myrelease-artifactory-ha-primary-1.
• Pass a parameter to helm install and helm upgrade

...
--set artifactory.node.persistence.existingClaim=true

Existing shared volume claim

In order to use an existing claim (for data and backup) that is to be shared across all nodes, you need to:

• Create PVCs with ReadWriteMany that match the naming conventions:

  {{ template "artifactory-ha.fullname" . }}-data-pvc-<claim-ordinal>
  {{ template "artifactory-ha.fullname" . }}-backup-pvc-<claim-ordinal>

An example that shows 2 existing claims to be used:

  myexample-artifactory-ha-data-pvc-0
  myexample-artifactory-ha-backup-pvc-0
  myexample-artifactory-ha-data-pvc-1
  myexample-artifactory-ha-backup-pvc-1

• Set the artifactory.persistence.fileSystem.existingSharedClaim.enabled in values.yaml to true:

-- set artifactory.persistence.fileSystem.existingSharedClaim.enabled=true
-- set artifactory.persistence.fileSystem.existingSharedClaim.numberOfExistingClaims=2

NFS

To use an NFS server as your cluster's storage, you need to

• Setup an NFS server. Get its IP as NFS_IP
• Create a data and backup directories on the NFS exported directory with write permissions to all
• Pass NFS parameters to helm install and helm upgrade

...
--set artifactory.persistence.type=nfs \
--set artifactory.persistence.nfs.ip=${NFS_IP} \
...

Google Storage

To use a Google Storage bucket as the cluster's filestore. See Google Storage Binary Provider

• Pass Google Storage parameters to helm install and helm upgrade

...
--set artifactory.persistence.type=google-storage \
--set artifactory.persistence.googleStorage.identity=${GCP_ID} \
--set artifactory.persistence.googleStorage.credential=${GCP_KEY} \
...

In order to use a GCP service account, Artifactory needs a gcp.credentials.json file in the same directory asa binaraystore.xml file.
This can be generated by running:
```bash
gcloud iam service-accounts keys create <file_name> --iam-account <service_account_name>

Which will produce the following, which can be saved to a file or copied into your values.yaml.

{
   "type": "service_account",
   "project_id": "<project_id>",
   "private_key_id": "?????",
   "private_key": "-----BEGIN PRIVATE KEY-----\n????????==\n-----END PRIVATE KEY-----\n",
   "client_email": "???@j<project_id>.iam.gserviceaccount.com",
   "client_id": "???????",
   "auth_uri": "https://accounts.google.com/o/oauth2/auth",
   "token_uri": "https://oauth2.googleapis.com/token",
   "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
   "client_x509_cert_url": "https://www.googleapis.com/robot/v1....."
}

One option is to create your own Secret and pass it to your helm install in a custom values.yaml

# Create the Kubernetes secret from the file you created earlier.
# IMPORTANT: The file must be called "gcp.credentials.json" because this is used later as the secret key!
kubectl create secret generic artifactory-gcp-creds --from-file=./gcp.credentials.json

Set this secret in your custom values.yaml

artifactory:
  persistence:
    googleStorage
      gcpServiceAccount:
        enabled: true
        customSecretName: artifactory-gcp-creds

Another option is to put your generated config directly in your custom values.yaml and the a secret will be created from it

artifactory:
  persistence:
    googleStorage
      gcpServiceAccount:
        enabled: true
        config: |
          {
             "type": "service_account",
             "project_id": "<project_id>",
             "private_key_id": "?????",
             "private_key": "-----BEGIN PRIVATE KEY-----\n????????==\n-----END PRIVATE KEY-----\n",
             "client_email": "???@j<project_id>.iam.gserviceaccount.com",
             "client_id": "???????",
             "auth_uri": "https://accounts.google.com/o/oauth2/auth",
             "token_uri": "https://oauth2.googleapis.com/token",
             "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
             "client_x509_cert_url": "https://www.googleapis.com/robot/v1....."
          }

AWS S3

NOTE Keep in mind that when using the aws-s3 persistence type, you will not be able to provide an IAM on the pod level. In order to grant permissions to Artifactory using an IAM role, you will have to attach the IAM role to the machine(s) on which Artifactory is running. This is due to the fact that the aws-s3 template uses the JetS3t library to interact with AWS. If you want to grant an IAM role at the pod level, see the AWS S3 Vs section.

To use an AWS S3 bucket as the cluster's filestore. See S3 Binary Provider

• Pass AWS S3 parameters to helm install and helm upgrade

...
# With explicit credentials:
--set artifactory.persistence.type=aws-s3 \
--set artifactory.persistence.awsS3.endpoint=${AWS_S3_ENDPOINT} \
--set artifactory.persistence.awsS3.region=${AWS_REGION} \
--set artifactory.persistence.awsS3.identity=${AWS_ACCESS_KEY_ID} \
--set artifactory.persistence.awsS3.credential=${AWS_SECRET_ACCESS_KEY} \
...

...
# With using existing IAM role
--set artifactory.persistence.type=aws-s3 \
--set artifactory.persistence.awsS3.endpoint=${AWS_S3_ENDPOINT} \
--set artifactory.persistence.awsS3.region=${AWS_REGION} \
--set artifactory.persistence.awsS3.roleName=${AWS_ROLE_NAME} \
...

NOTE: Make sure S3 endpoint and region match. See AWS documentation on endpoint

AWS S3 V3

To use an AWS S3 bucket as the cluster's filestore and access it with the official AWS SDK, See S3 Official SDK Binary Provider. This filestore template uses the official AWS SDK, unlike the aws-s3 implementation that uses the JetS3t library. Use this template if you want to attach an IAM role to the Artifactory pod directly (as opposed to attaching it to the machine/s that Artifactory will run on).

NOTE This will have to be combined with a k8s mechanism for attaching IAM roles to pods, like kube2iam or anything similar.

• Pass AWS S3 V3 parameters and the annotation pointing to the IAM role (when using an IAM role. this is kube2iam specific and may vary depending on the implementation) to helm install and helm upgrade

# With explicit credentials:
--set artifactory.persistence.type=aws-s3-v3 \
--set artifactory.persistence.awsS3V3.region=${AWS_REGION} \
--set artifactory.persistence.awsS3V3.bucketName=${AWS_S3_BUCKET_NAME} \
--set artifactory.persistence.awsS3V3.identity=${AWS_ACCESS_KEY_ID} \
--set artifactory.persistence.awsS3V3.credential=${AWS_SECRET_ACCESS_KEY} \
...

# With using existing IAM role
--set artifactory.persistence.type=aws-s3-v3 \
--set artifactory.persistence.awsS3V3.region=${AWS_REGION} \
--set artifactory.persistence.awsS3V3.bucketName=${AWS_S3_BUCKET_NAME} \
--set artifactory.annotations.'iam\.amazonaws\.com/role'=${AWS_IAM_ROLE_ARN}
...

To enable Direct Cloud Storage Download

...
--set artifactory.persistence.awsS3V3.enableSignedUrlRedirect=true \
...

Microsoft Azure Blob Storage

To use Azure Blob Storage as the cluster's filestore. See Azure Blob Storage Binary Provider

• Pass Azure Blob Storage parameters to helm install and helm upgrade

...
--set artifactory.persistence.type=azure-blob \
--set artifactory.persistence.azureBlob.accountName=${AZURE_ACCOUNT_NAME} \
--set artifactory.persistence.azureBlob.accountKey=${AZURE_ACCOUNT_KEY} \
--set artifactory.persistence.azureBlob.endpoint=${AZURE_ENDPOINT} \
--set artifactory.persistence.azureBlob.containerName=${AZURE_CONTAINER_NAME} \
...

Custom binarystore.xml

You have an option to provide a custom binarystore.xml.
There are two options for this

1. Editing directly in values.yaml

artifactory:
  persistence:
    binarystoreXml: |
      <!-- The custom XML snippet -->
      <config version="v1">
          <chain template="file-system"/>
      </config>      

2. Create your own Secret and pass it to your helm install command

# Prepare your custom Secret file (custom-binarystore.yaml)
kind: Secret
apiVersion: v1
metadata:
  name: custom-binarystore
  labels:
    app: artifactory
    chart: artifactory
stringData:
  binarystore.xml: |-
      <!-- The custom XML snippet -->
      <config version="v1">
          <chain template="file-system"/>
      </config>      

# Create a secret from the file
kubectl apply -n artifactory -f ./custom-binarystore.yaml

# Pass it to your helm install command:
helm upgrade --install artifactory-ha --set artifactory.persistence.customBinarystoreXmlSecret=custom-binarystore --namespace artifactory-ha center/jfrog/artifactory-ha

Create a unique Master Key

Alternatively, you can create a secret containing the master key manually and pass it to the template at install/upgrade time.

# Create a key
export MASTER_KEY=$(openssl rand -hex 32)
echo ${MASTER_KEY}

# Create a secret containing the key. The key in the secret must be named master-key
kubectl create secret generic my-secret --from-literal=master-key=${MASTER_KEY}

# Pass the created secret to helm
helm upgrade --install artifactory-ha --set artifactory.masterKeySecretName=my-secret --namespace artifactory-ha center/jfrog/artifactory-ha

NOTE: In either case, make sure to pass the same master key on all future calls to helm install and helm upgrade! In the first case, this means always passing --set artifactory.masterKey=${MASTER_KEY}. In the second, this means always passing --set artifactory.masterKeySecretName=my-secret and ensuring the contents of the secret remain unchanged.

Special Upgrade Notes

MasterKey during 6.x to 7.x Migration (App version)

NOTE: 6.x only supports masterKey with 16 hex (32 characters) and if you have set masterKey using openssl rand -hex 32 (64 characters) in 6.x, only the first 32 characters are used and rest are ignored. Hence, during 6.x to 7.x migration, we trim first 32 characters and set masterkey, which implies 7.x still uses the trimmed masterkey of 6.x. Hence, artifactory.masterKey should not be passed during migration from 6.x to 7.x.

Create a unique Join Key

Artifactory requires a unique join key. By default the chart has one set in values.yaml (artifactory.joinKey).

This key is for demo purpose and should not be used in a production environment!

You should generate a unique key and pass it to the template at install/upgrade time.

# Create a key
export JOIN_KEY=$(openssl rand -hex 32)
echo ${JOIN_KEY}

# Pass the created join key to helm
helm upgrade --install artifactory-ha --set artifactory.joinKey=${JOIN_KEY} --namespace artifactory-ha center/jfrog/artifactory-ha

Alternatively, you can create a secret containing the join key manually and pass it to the template at install/upgrade time.

# Create a key
export JOIN_KEY=$(openssl rand -hex 32)
echo ${JOIN_KEY}

# Create a secret containing the key. The key in the secret must be named join-key
kubectl create secret generic my-secret --from-literal=join-key=${JOIN_KEY}

# Pass the created secret to helm
helm upgrade --install artifactory-ha --set artifactory.joinKeySecretName=my-secret --namespace artifactory-ha center/jfrog/artifactory-ha

NOTE: In either case, make sure to pass the same join key on all future calls to helm install and helm upgrade! This means always passing --set artifactory.joinKey=${JOIN_KEY}. In the second, this means always passing --set artifactory.joinKeySecretName=my-secret and ensuring the contents of the secret remain unchanged..

Install Artifactory HA license

For activating Artifactory HA, you must install an appropriate license. There are three ways to manage the license. Artifactory UI, REST API, or a Kubernetes Secret.

The easier and recommended way is the Artifactory UI. Using the Kubernetes Secret or REST API is for advanced users and is better suited for automation.

IMPORTANT: You should use only one of the following methods. Switching between them while a cluster is running might disable your Artifactory HA cluster!

Artifactory UI

Once primary cluster is running, open Artifactory UI and insert the license(s) in the UI. See HA installation and setup for more details. Note that you should enter all licenses at once, with each license is separated by a newline. If you add the licenses one at a time, you may get redirected to a node without a license and the UI won't load for that node.

REST API

You can add licenses via REST API (https://www.jfrog.com/confluence/display/RTF/Artifactory+REST+API#ArtifactoryRESTAPI-InstallHAClusterLicenses). Note that the REST API expects "\n" for the newlines in the licenses.

Kubernetes Secret

You can deploy the Artifactory license(s) as a Kubernetes secret. Prepare a text file with the license(s) written in it. If writing multiple licenses (must be in the same file), it's important to put two new lines between each license block!

# Create the Kubernetes secret (assuming the local license file is 'art.lic')
kubectl create secret generic artifactory-cluster-license --from-file=./art.lic

# Pass the license to helm
helm upgrade --install artifactory-ha --set artifactory.license.secret=artifactory-cluster-license,artifactory.license.dataKey=art.lic --namespace artifactory-ha center/jfrog/artifactory-ha

NOTE: This method is relevant for initial deployment only! Once Artifactory is deployed, you should not keep passing these parameters as the license is already persisted into Artifactory's storage (they will be ignored). Updating the license should be done via Artifactory UI or REST API.

Create the secret as part of the helm release

values.yaml

artifactory:
  license:
    licenseKey: |-
      <LICENSE_KEY1>


      <LICENSE_KEY2>


      <LICENSE_KEY3>      

helm upgrade --install artifactory-ha -f values.yaml --namespace artifactory-ha center/jfrog/artifactory-ha

NOTE: This method is relevant for initial deployment only! Once Artifactory is deployed, you should not keep passing these parameters as the license is already persisted into Artifactory's storage (they will be ignored). Updating the license should be done via Artifactory UI or REST API. If you want to keep managing the artifactory license using the same method, you can use the copyOnEveryStartup example shown in the values.yaml file

copyOnEveryStartup feature

Files stored in the /artifactory-extra-conf directory are only copied to the ARTIFACTORY_HOME/etc directory upon the first startup. In some cases, you want your configuration files to be copied to the ARTIFACTORY_HOME/etc directory on every startup. Two examples for that would be:

1. the binarstore.xml file. If you use the default behaviour, your binarystore.xml configuration will only be copied on the first startup, which means that changes you make over time to the binaryStoreXml configuration will not be applied. In order to make sure your changes are applied on every startup, do the following: Create a values file with the following values:

artifactory:
  copyOnEveryStartup:
    - source: /artifactory_bootstrap/binarystore.xml
      target: etc/artifactory/

Install the helm chart with the values file you created:

helm upgrade --install artifactory-ha --namespace artifactory-ha center/jfrog/artifactory-ha -f values.yaml

2. Any custom configuration file you have to configure artifactory, such as logback.xml: Create a config map with your logback.xml configuration.

Create a values file with the following values:

artifactory:
  ## Create a volume pointing to the config map with your configuration file
  customVolumes: |
    - name: logback-xml-configmap
      configMap:
        name: logback-xml-configmap    
  customVolumeMounts: |
    - name: logback-xml-configmap
      mountPath: /tmp/artifactory-logback/    
  copyOnEveryStartup:
    - source: /tmp/artifactory-logback/*
      target: etc/

Install the helm chart with the values file you created:

helm upgrade --install artifactory-ha --namespace artifactory-ha center/jfrog/artifactory-ha -f values.yaml

Configure NetworkPolicy

NetworkPolicy specifies what ingress and egress is allowed in this namespace. It is encouraged to be more specific whenever possible to increase security of the system.

In the networkpolicy section of values.yaml you can specify a list of NetworkPolicy objects.

For podSelector, ingress and egress, if nothing is provided then a default - {} is applied which is to allow everything.

A full (but very wide open) example that results in 2 NetworkPolicy objects being created:

networkpolicy:
  # Allows all ingress and egress to/from artifactory primary and member pods.
  - name: artifactory
    podSelector:
      matchLabels:
        app: artifactory-ha
    egress:
    - {}
    ingress:
    - {}
  # Allows connectivity from artifactory-ha pods to postgresql pods, but no traffic leaving postgresql pod.
  - name: postgresql
    podSelector:
      matchLabels:
        app: postgresql
    ingress:
    - from:
      - podSelector:
          matchLabels:
            app: artifactory-ha

Artifactory JMX Configuration

** You can see some information about the exposed MBeans here - https://www.jfrog.com/confluence/display/RTF/Artifactory+JMX+MBeans

Enable JMX in your deployment:

helm upgrade --install artifactory \
    --set artifactory.primary.javaOpts.jmx.enabled=true \
    --set artifactory.node.javaOpts.jmx.enabled=true \
    --namespace artifactory-ha center/jfrog/artifactory-ha

This will enable access to Artifactory with JMX on the default port (9010). ** You have the option to change the port by setting artifactory.primary.javaOpts.jmx.port and artifactory.node.javaOpts.jmx.port to your choice of port

In order to connect to Artifactory using JMX with jconsole (or any similar tool) installed on your computer, follow the following steps:

1. Enable JMX as described above and Change the Artifactory service to be of type LoadBalancer:

helm upgrade --install artifactory \
    --set artifactory.primary.javaOpts.jmx.enabled=true \
    --set artifactory.node.javaOpts.jmx.enabled=true \
    --set artifactory.service.type=LoadBalancer \
    --namespace artifactory-ha center/jfrog/artifactory-ha

2. The default setting for java.rmi.server.hostname is the service name (this is also configurable with artifactory.primary.javaOpts.jmx.host and artifactory.node.javaOpts.jmx.host), So in order to connect to Artifactory with jconsole you should map the Artifactory kuberentes service IP to the service name using your hosts file as such:

<artifactory-primary-service-ip>    artifactory-ha-<release-name>-primary
<artifactory-node-service-ip>       <release-name>

3. Launch jconsole with the service address and port:

jconsole artifactory-ha-<release-name>-primary:<primary-jmx-port>
jconsole <release-name>:<node-jmx-port>

Bootstrapping Artifactory admin password

You can bootstrap the admin user password as described in the bootstrap Artifactory admin credentials guide.

1. Create admin-creds-values.yaml and provide the IP (By default 127.0.0.1) and password:

artifactory:
  admin:
    ip: "<IP_RANGE>" # Example: "*" to allow access from anywhere
    username: "admin"
    password: "<PASSWD>"

2. Apply the admin-creds-values.yaml file:

helm upgrade --install artifactory --namespace artifactory-ha center/jfrog/artifactory-ha -f admin-creds-values.yaml

Bootstrapping Artifactory configuration

IMPORTANT: Bootstrapping Artifactory needs license. Pass license as shown in above section.

• User guide to bootstrap Artifactory Global Configuration
• User guide to bootstrap Artifactory Security Configuration

1. Create bootstrap-config.yaml with artifactory.config.import.xml and security.import.xml as shown below:

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-release-bootstrap-config
data:
  artifactory.config.import.xml: |
    <config contents>    
  security.import.xml: |
    <config contents>    

2. Create configMap in Kubernetes:

kubectl apply -f bootstrap-config.yaml

3. Pass the configMap to helm

helm upgrade --install artifactory-ha --set artifactory.license.secret=artifactory-cluster-license,artifactory.license.dataKey=art.lic,artifactory.configMapName=my-release-bootstrap-config --namespace artifactory-ha center/jfrog/artifactory-ha

Use custom nginx.conf with Nginx

Steps to create configMap with nginx.conf

• Create nginx.conf file.

kubectl create configmap nginx-config --from-file=nginx.conf

• Pass configMap to helm install

helm upgrade --install artifactory-ha --set nginx.customConfigMap=nginx-config --namespace artifactory-ha center/jfrog/artifactory-ha

Scaling your Artifactory cluster

A key feature in Artifactory HA is the ability to set an initial cluster size with --set artifactory.node.replicaCount=${CLUSTER_SIZE} and if needed, resize it.

Before scaling

IMPORTANT: When scaling, you need to explicitly pass the database password if it's an auto generated one (this is the default with the enclosed PostgreSQL helm chart).

Get the current database password

export DB_PASSWORD=$(kubectl get $(kubectl get secret -o name | grep postgresql) -o jsonpath="{.data.postgresql-password}" | base64 --decode)

Use --set postgresql.postgresqlPassword=${DB_PASSWORD} with every scale action to prevent a miss configured cluster!

Scale up

Let's assume you have a cluster with 2 member nodes, and you want to scale up to 3 member nodes (a total of 4 nodes).

# Scale to 4 nodes (1 primary and 3 member nodes)
helm upgrade --install artifactory-ha --set artifactory.node.replicaCount=3 --set postgresql.postgresqlPassword=${DB_PASSWORD} --namespace artifactory-ha center/jfrog/artifactory-ha

Scale down

Let's assume you have a cluster with 3 member nodes, and you want to scale down to 2 member node.

# Scale down to 2 member nodes
helm upgrade --install artifactory-ha --set artifactory.node.replicaCount=2 --set postgresql.postgresqlPassword=${DB_PASSWORD} --namespace artifactory-ha center/jfrog/artifactory-ha

• NOTE: Since Artifactory is running as a Kubernetes Stateful Set, the removal of the node will not remove the persistent volume. You need to explicitly remove it

# List PVCs
kubectl get pvc

# Remove the PVC with highest ordinal!
# In this example, the highest node ordinal was 2, so need to remove its storage.
kubectl delete pvc volume-artifactory-node-2

Use an external Database

For production grade installations it is recommended to use an external PostgreSQL with a static password

PostgreSQL

There are cases where you will want to use external PostgreSQL with a different database name e.g. my-artifactory-db, then you need set a custom PostgreSQL connection URL, where my-artifactory-db is the database name.

This can be done with the following parameters

...
--set postgresql.enabled=false \
--set database.type=postgresql \
--set database.driver=org.postgresql.Driver \
--set database.url='jdbc:postgresql://${DB_HOST}:${DB_PORT}/my-artifactory-db' \
--set database.user=${DB_USER} \
--set database.password=${DB_PASSWORD} \
...

NOTE: You must set postgresql.enabled=false in order for the chart to use the database.* parameters. Without it, they will be ignored!

Other DB type

There are cases where you will want to use a different database and not the enclosed PostgreSQL. See more details on configuring the database

The official Artifactory Docker images include the PostgreSQL database driver. For other database types, you will have to add the relevant database driver to Artifactory's tomcat/lib

This can be done with the following parameters

# Make sure your Artifactory Docker image has the MySQL database driver in it
...
--set postgresql.enabled=false \
--set artifactory.preStartCommand="mkdir -p /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib; cd /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib && wget -O /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib/mysql-connector-java-5.1.41.jar https://jcenter.bintray.com/mysql/mysql-connector-java/5.1.41/mysql-connector-java-5.1.41.jar" \
--set database.type=mysql \
--set database.driver=com.mysql.jdbc.Driver \
--set database.url=${DB_URL} \
--set database.user=${DB_USER} \
--set database.password=${DB_PASSWORD} \
...

NOTE: You must set postgresql.enabled=false in order for the chart to use the database.* parameters. Without it, they will be ignored!

Configuring Artifactory with external Oracle database

To use artifactory with oracledb the required instant client library files, libaio has to be copied to tomcat lib. Also set LD_LIBRARY_PATH env variable.

1. Create a value file with the configuration

postgresql:
  enabled: false
database:
  type: oracle
  driver: oracle.jdbc.OracleDriver
  url: <DB_URL>
  user: <DB_USER>
  password: <DB_PASSWORD>
artifactory:
  preStartCommand: "mkdir -p /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib; cd /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib && wget -O instantclient-basic-linux.x64-19.6.0.0.0dbru.zip https://download.oracle.com/otn_software/linux/instantclient/19600/instantclient-basic-linux.x64-19.6.0.0.0dbru.zip && unzip -jn instantclient-basic-linux.x64-19.6.0.0.0dbru.zip && wget -O libaio1_0.3.110-3_amd64.deb http://ftp.br.debian.org/debian/pool/main/liba/libaio/libaio1_0.3.110-3_amd64.deb &&  dpkg-deb -x libaio1_0.3.110-3_amd64.deb . && cp lib/x86_64-linux-gnu/* ."  
  extraEnvironmentVariables:
  - name: LD_LIBRARY_PATH
    value: /opt/jfrog/artifactory/var/bootstrap/artifactory/tomcat/lib

2. Install Artifactory with the values file you created:

helm upgrade --install artifactory center/jfrog/artifactory-ha --namespace artifactory -f values-oracle.yaml

NOTE: If its an upgrade from 6.x to 7.x, add same preStartCommand under artifactory.migration.preStartCommand

Using pre-existing Kubernetes Secret

If you store your database credentials in a pre-existing Kubernetes Secret, you can specify them via database.secrets instead of database.user and database.password:

# Create a secret containing the database credentials
kubectl create secret generic my-secret --from-literal=user=${DB_USER} --from-literal=password=${DB_PASSWORD}
...
--set postgresql.enabled=false \
--set database.secrets.user.name=my-secret \
--set database.secrets.user.key=user \
--set database.secrets.password.name=my-secret \
--set database.secrets.password.key=password \
...

Deleting Artifactory

To delete the Artifactory HA cluster

On helm v2:

helm delete --purge artifactory-ha

On helm v3:

helm delete artifactory-ha --namespace artifactory-ha

This will completely delete your Artifactory HA cluster. NOTE: Since Artifactory is running as Kubernetes Stateful Sets, the removal of the helm release will not remove the persistent volumes. You need to explicitly remove them

kubectl delete pvc -l release=artifactory-ha

See more details in the official Kubernetes Stateful Set removal page

Custom Docker registry for your images

If you need to pull your Docker images from a private registry (for example, when you have a custom image with a MySQL database driver), you need to create a Kubernetes Docker registry secret and pass it to helm

# Create a Docker registry secret called 'regsecret'
kubectl create secret docker-registry regsecret --docker-server=${DOCKER_REGISTRY} --docker-username=${DOCKER_USER} --docker-password=${DOCKER_PASS} --docker-email=${DOCKER_EMAIL}

Once created, you pass it to helm

helm upgrade --install artifactory-ha --set imagePullSecrets=regsecret --namespace artifactory-ha center/jfrog/artifactory-ha

Logger sidecars

This chart provides the option to add sidecars to tail various logs from Artifactory. See the available values in values.yaml

Get list of containers in the pod

kubectl get pods -n <NAMESPACE> <POD_NAME> -o jsonpath='{.spec.containers[*].name}' | tr ' ' '\n'

View specific log

kubectl logs -n <NAMESPACE> <POD_NAME> -c <LOG_CONTAINER_NAME>

Custom init containers

There are cases where a special, unsupported init processes is needed like checking something on the file system or testing something before spinning up the main container.

For this, there is a section for writing custom init containers before and after the predefined init containers in the values.yaml . By default it's commented out

artifactory:
  ## Add custom init containers executed before predefined init containers
  customInitContainersBegin: |
    ## Init containers template goes here ##    
  ## Add custom init containers executed after predefined init containers
  customInitContainers: |
    ## Init containers template goes here ##    

Custom sidecar containers

There are cases where an extra sidecar container is needed. For example monitoring agents or log collection.

For this, there is a section for writing a custom sidecar container in the values.yaml. By default it's commented out

artifactory:
  ## Add custom sidecar containers
  customSidecarContainers: |
    ## Sidecar containers template goes here ##    

You can configure the sidecar to run as a custom user if needed by setting the following in the container template

  # Example of running container as root (id 0)
  securityContext:
    runAsUser: 0
    fsGroup: 0

Custom volumes

If you need to use a custom volume in a custom init or sidecar container, you can use this option.

For this, there is a section for defining custom volumes in the values.yaml. By default it's commented out

artifactory:
  ## Add custom volumes
  customVolumes: |
    ## Custom volume comes here ##    

Custom secrets

If you need to add a custom secret in a custom init or sidecar container, you can use this option.

For this, there is a section for defining custom secrets in the values.yaml. By default it's commented out

artifactory:
  # Add custom secrets - secret per file
    customSecrets:
      - name: custom-secret
        key: custom-secret.yaml
        data: >
          secret data          

To use a custom secret, need to define a custom volume.

artifactory:
  ## Add custom volumes
  customVolumes: |
    - name: custom-secret
      secret:
        secretName: custom-secret    

To use a volume, need to define a volume mount as part of a custom init or sidecar container.

artifactory:
  customSidecarContainers:
    - name: side-car-container
      volumeMounts:
      - name: custom-secret
        mountPath: /opt/custom-secret.yaml
        subPath: custom-secret.yaml
        readOnly: true

Add Artifactory User Plugin during installation

If you need to add Artifactory User Plugin, you can use this option.

Create a secret with Artifactory User Plugin by following command:

# Secret with single user plugin
kubectl  create secret generic archive-old-artifacts --from-file=archiveOldArtifacts.groovy --namespace=artifactory-ha

# Secret with single user plugin with configuration file
kubectl  create secret generic webhook --from-file=webhook.groovy  --from-file=webhook.config.json.sample --namespace=artifactory-ha

Add plugin secret names to plugins.yaml as following:

artifactory:
  userPluginSecrets:
    - archive-old-artifacts
    - webhook

You can now pass the created plugins.yaml file to helm install command to deploy Artifactory with user plugins as follows:

helm upgrade --install artifactory-ha -f plugins.yaml --namespace artifactory-ha center/jfrog/artifactory-ha

Alternatively, you may be in a situation in which you would like to create a secret in a Helm chart that depends on this chart. In this scenario, the name of the secret is likely dynamically generated via template functions, so passing a statically named secret isn't possible. In this case, the chart supports evaluating strings as templates via the tpl function - simply pass the raw string containing the templating language used to name your secret as a value instead by adding the following to your chart's values.yaml file:

artifactory-ha: # Name of the artifactory-ha dependency
  artifactory:
    userPluginSecrets:
      - '{{ template "my-chart.fullname" . }}'

For additional information, please refer here.

Provide custom configMaps to Artifactory

If you want to mount a custom file to Artifactory, either an init shell script or a custom configuration file (such as logback.xml), you can use this option.

Create a configmaps.yaml file with the following content:

artifactory:
  configMaps: |
    logback.xml: |
      <configuration debug="false">
          <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
              <encoder class="ch.qos.logback.core.encoder.LayoutWrappingEncoder">
                  <layout class="org.artifactory.logging.layout.BackTracePatternLayout">
                      <pattern>%date [%-5level] \(%-20c{3}:%L\) %message%n</pattern>
                  </layout>
              </encoder>
          </appender>

          <logger name="/artifactory">
              <level value="INFO"/>
              <appender-ref ref="CONSOLE"/>
          </logger>
          <logger name="org.eclipse.jetty">
              <level value="WARN"/>
              <appender-ref ref="CONSOLE"/>
          </logger>
      </configuration>

    my-custom-post-start-hook.sh: |
      echo "This is my custom post start hook"    

  customVolumeMounts: |
    - name: artifactory-configmaps
      mountPath: /tmp/my-config-map    

  postStartCommand: |
    chmod +x /tmp/my-config-map/my-custom-post-start-hook.sh;
    /tmp/my-config-map/my-custom-post-start-hook.sh;    

  copyOnEveryStartup:
    - source: /tmp/my-config-map/logback.xml
      target: etc/

and use it with you helm install/upgrade:

helm upgrade --install artifactory-ha -f configmaps.yaml --namespace artifactory-ha center/jfrog/artifactory-ha

This will, in turn:

• create a configMap with the files you specified above
• create a volume pointing to the configMap with the name artifactory-configmaps
• Mount said configMap onto /tmp/my-config-map using a customVolumeMounts
• Set the shell script we mounted as the postStartCommand
• Copy the logback.xml file to its proper location in the $ARTIFACTORY_HOME/etc directory.

Establishing TLS and Adding certificates

In HTTPS, the communication protocol is encrypted using Transport Layer Security (TLS). By default, TLS between JFrog Platform nodes is disabled. When TLS is enabled, JFrog Access acts as the Certificate Authority (CA) signs the TLS certificates used by all the different JFrog Platform nodes.

To establish TLS between JFrog Platform nodes: Enable TLS by changing the tls entry (under the security section) in the access.config.yaml file. For more info, Please refer here

To enable tls in charts, set tls to true under access in values.yaml. By default it's false

access:
  accessConfig:
    security:
      tls: true

To add custom tls certificates, create a tls secret from the certificate files.

kubectl create secret tls <tls-secret-name> --cert=ca.crt --key=ca.private.key

For resetting access certificates , you can set resetAccessCAKeys to true under access section in values.yaml and perform an helm upgrade.

• Note : Once helm upgrade is done, set resetAccessCAKeys to false for subsequent upgrades (to avoid resetting access certificates on every helm upgrade)

access:
  accessConfig:
    security:
      tls: true
  customCertificatesSecretName: <tls-secret-name>
  resetAccessCAKeys: true

Artifactory filebeat

If you want to collect logs from your Artifactory installation and send them to a central log collection solution like ELK, you can use this option.

Create a filebeat.yaml values file with the following content:

filebeat:
  enabled: true
  logstashUrl: <YOUR_LOGSTASH_URL>
  resources:
    requests:
      memory: "100Mi"
      cpu: "100m"
    limits:
      memory: "100Mi"
      cpu: "100m"

You can optionally customize the filebeat.yaml to send output to a different location like so:

filebeat:
  enabled: true
  filebeatYml: |
    <YOUR_CUSTOM_FILEBEAT_YML>    

and use it with you helm install/upgrade:

helm upgrade --install artifactory-ha -f filebeat.yaml --namespace artifactory-ha center/jfrog/artifactory

This will start sending your Artifactory logs to the log aggregator of your choice, based on your configuration in the filebeatYml

Install Artifactory HA with Nginx and Terminate SSL in Nginx Service(LoadBalancer).

To install the helm chart with performing SSL offload in the LoadBalancer layer of Nginx For Ex: Using AWS ACM certificates to do SSL offload in the loadbalancer layer. In order to do that, simply add the following to a artifactory-ssl-values.yaml file:

  nginx:
    https:
      enabled: false
    service:
      ssloffload: true
      annotations:
        service.beta.kubernetes.io/aws-load-balancer-ssl-cert: "arn:aws:acm:xx-xxxx:xxxxxxxx:certificate/xxxxxxxxxxxxx"
        service.beta.kubernetes.io/aws-load-balancer-backend-protocol: "http"
        service.beta.kubernetes.io/aws-load-balancer-ssl-ports: "https"

and use it with you helm install/upgrade:

helm upgrade --install artifactory -f artifactory-ssl-values.yaml --namespace artifactory center/jfrog/artifactory

Ingress and TLS

To get Helm to create an ingress object with a hostname, add these below lines to artifactory-ingress-values.yaml file

  ingress:
    enabled: true
    hosts:
      - artifactory.company.com
  artifactory:
    service:
      type: NodePort
  nginx
    enabled: false

and use it with you helm install/upgrade:

helm upgrade --install artifactory -f artifactory-ingress-values.yaml--namespace artifactory center/jfrog/artifactory

If your cluster allows automatic creation/retrieval of TLS certificates (e.g. cert-manager), please refer to the documentation for that mechanism.

To manually configure TLS, first create/retrieve a key & certificate pair for the address(es) you wish to protect. Then create a TLS secret in the namespace:

kubectl create secret tls artifactory-tls --cert=path/to/tls.cert --key=path/to/tls.key

Include the secret's name, along with the desired hostnames, in the Artifactory Ingress TLS section of your custom values.yaml file:

  ingress:
    ## If true, Artifactory Ingress will be created
    ##
    enabled: true

    ## Artifactory Ingress hostnames
    ## Must be provided if Ingress is enabled
    ##
    hosts:
      - artifactory.domain.com
    annotations:
      kubernetes.io/tls-acme: "true"
    ## Artifactory Ingress TLS configuration
    ## Secrets must be manually created in the namespace
    ##
    tls:
      - secretName: artifactory-tls
        hosts:
          - artifactory.domain.com

Ingress annotations

This example specifically enables Artifactory to work as a Docker Registry using the Repository Path method. See Artifactory as Docker Registry documentation for more information about this setup.

ingress:
  enabled: true
  defaultBackend:
    enabled: false
  hosts:
    - myhost.example.com
  annotations:
    ingress.kubernetes.io/force-ssl-redirect: "true"
    ingress.kubernetes.io/proxy-body-size: "0"
    ingress.kubernetes.io/proxy-read-timeout: "600"
    ingress.kubernetes.io/proxy-send-timeout: "600"
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/configuration-snippet: |
      rewrite ^/(v2)/token /artifactory/api/docker/null/v2/token;
      rewrite ^/(v2)/([^\/]*)/(.*) /artifactory/api/docker/$2/$1/$3;      
    nginx.ingress.kubernetes.io/proxy-body-size: "0"
  tls:
    - hosts:
      - "myhost.example.com"

Ingress additional rules

You have the option to add additional ingress rules to the Artifactory ingress. An example for this use case can be routing the /xray path to Xray. In order to do that, simply add the following to a artifactory-ha-values.yaml file:

ingress:
  enabled: true

  defaultBackend:
    enabled: false

  annotations:
    kubernetes.io/ingress.class: nginx
    nginx.ingress.kubernetes.io/configuration-snippet: |
      rewrite "(?i)/xray(/|$)(.*)" /$2 break;      

  additionalRules: |
    - host: <MY_HOSTNAME>
      http:
        paths:
          - path: /
            backend:
              serviceName: <XRAY_SERVER_SERVICE_NAME>
              servicePort: <XRAY_SERVER_SERVICE_PORT>
          - path: /xray
            backend:
              serviceName: <XRAY_SERVER_SERVICE_NAME>
              servicePort: <XRAY_SERVER_SERVICE_PORT>
          - path: /artifactory
            backend:
              serviceName: {{ template "artifactory.nginx.fullname" . }}
              servicePort: {{ .Values.nginx.externalPortHttp }}    

and running:

helm upgrade --install artifactory-ha --namespace artifactory-ha center/jfrog/artifactory-ha -f artifactory-ha-values.yaml

Dedicated Ingress object for replicator service

You have the option to add additional ingress object to the Replicator service. An example for this use case can be routing the /replicator/ path to Artifactory. In order to do that, simply add the following to a artifactory-values.yaml file:

artifactory:
  replicator:
    enabled: true
    ingress:
      name: <MY_INGRESS_NAME>
      hosts:
        - myhost.example.com
      annotations:
        kubernetes.io/ingress.class: nginx
        nginx.ingress.kubernetes.io/proxy-buffering: "off"
        nginx.ingress.kubernetes.io/configuration-snippet: |
          chunked_transfer_encoding on;          
      tls:
        - hosts:
          - "myhost.example.com"
          secretName: <CUSTOM_SECRET>

Ingress behind another load balancer

If you are running a load balancer, that is used to offload the TLS, in front of Nginx Ingress Controller, or if you are setting X-Forwarded-* headers, you might want to enable 'use-forwarded-headers=true' option. Otherwise nginx will be filling those headers with the request information it receives from the external load balancer.

To enable it with helm install

helm upgrade --install nginx-ingress --namespace nginx-ingress center/kubernetes-ingress-nginx/ingress-nginx --set-string controller.config.use-forwarded-headers=true

or helm upgrade

helm upgrade nginx-ingress --set-string controller.config.use-forwarded-headers=true center/kubernetes-ingress-nginx/ingress-nginx

or create a values.yaml file with the following content:

controller:
  config:
    use-forwarded-headers: "true"

Then install nginx-ingress with the values file you created:

helm upgrade --install nginx-ingress --namespace nginx-ingress center/kubernetes-ingress-nginx/ingress-nginx -f values.yaml

Log Analytics

FluentD, Prometheus and Grafana

To configure Prometheus and Grafana to gather metrics from Artifactory through the use of FluentD, please refer to the log analytics repo:

https://github.com/jfrog/log-analytics-prometheus

That repo contains a file artifactory-ha-values.yaml that can be used to deploy Prometheus, Service Monitor, and Grafana with this chart.

Useful links

• https://www.jfrog.com/confluence/display/EP/Getting+Started
• https://www.jfrog.com/confluence/display/RTF/Installing+Artifactory
• https://www.jfrog.com/confluence/