fix: merge conflict

.github/workflows/integration_test.yaml

@@ -10,7 +10,7 @@ jobs:
     with:
       channel: 1.28-strict/stable
       extra-arguments: |
-        --kube-config ${GITHUB_WORKSPACE}/kube-config
+        --kube-config=${GITHUB_WORKSPACE}/kube-config
       modules: '["test_auth_proxy.py", "test_cos.py", "test_ingress.py", "test_jenkins.py", "test_k8s_agent.py", "test_machine_agent.py", "test_plugins.py", "test_proxy.py", "test_upgrade.py", "test_external_agent.py"]'
       pre-run-script: |
         -c "sudo microk8s config > ${GITHUB_WORKSPACE}/kube-config
@@ -19,4 +19,4 @@ jobs:
       juju-channel: 3.1/stable
       self-hosted-runner: true
       self-hosted-runner-label: "xlarge"
-      microk8s-addons: "dns ingress rbac storage metallb:10.15.119.2-10.15.119.4"
+      microk8s-addons: "dns ingress rbac storage metallb:10.15.119.2-10.15.119.4 registry"

.trivyignore

@@ -1,17 +1,11 @@
-# Jenkins CVEs
-CVE-2016-1000027
-CVE-2024-22259
-CVE-2024-22257
-# Jenkins Plugin Manager CVEs
-CVE-2023-5072
-GHSA-4jq9-2xhw-jpx7
-CVE-2024-23898
-CVE-2024-25710
-CVE-2024-26308
-CVE-2024-22201
-CVE-2024-22243
 # Fixed in 5.3.33
 CVE-2024-22259
 # Fixed in 5.7.12
 CVE-2024-22257
 CVE-2024-22262
+# Jenkins Plugin Manager CVEs
+CVE-2016-1000027
+CVE-2023-5072
+CVE-2024-23898
+# Other
+CVE-2023-45288

docs/how-to/backup-and-restore-jenkins.md

@@ -0,0 +1,61 @@
+# Backup and restore Jenkins
+A backup is a snapshot of the Jenkins data (jobs, configurations, secrets, plugins, etc.) at a given point in time. This backup can be used to:
+* Restore Jenkins to a previous stable state (during disaster recovery).
+* Migrate data to a new Jenkins charm instance.
+
+## Create a backup
+1. Create the backup script
+From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-administration/backing-up/), This script backs up the most essential files as mentioned in the article:
+* The `master.key` file.
+* Job-related files in the `./jobs`, `./builds` and `./workspace` folders.
+* Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
+
+```bash
+cat <<EOF > backup.sh
+#!/bin/bash
+export JENKINS_HOME=/var/lib/jenkins
+export JENKINS_BACKUP=/mnt/backup
+
+echo "running backup as \$(whoami) in \$(pwd)"
+mkdir -p \$JENKINS_BACKUP
+cp \$JENKINS_HOME/secrets/master.key \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/jobs \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/builds \$JENKINS_BACKUP
+cp -r \$JENKINS_HOME/workspace \$JENKINS_BACKUP
+mkdir -p \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.hpi \$JENKINS_BACKUP/plugins
+cp -r \$JENKINS_HOME/plugins/*.jpi \$JENKINS_BACKUP/plugins
+
+chown -R 2000:2000\$JENKINS_BACKUP
+tar zcvf jenkins_backup.tar.gz --directory=/mnt backup
+EOF
+
+chmod +x backup.sh
+```
+2. Transfer the backup script above to the running unit of the Jenkins-k8s charm and run it
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./backup.sh $JENKINS_UNIT:/backup.sh
+juju ssh  --container jenkins $JENKINS_UNIT /backup.sh
+```
+3. Retrieve the compressed backup file
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins $JENKINS_UNIT:/jenkins_backup.tar.gz jenkins_backup.tar.gz
+```
+You now have the compressed Jenkins data on your host system.
+
+## Restore the backup on a new (or existing) charm instance
+1. Restore the backup on the Jenkins charm unit.
+```bash
+JENKINS_UNIT=jenkins-k8s/0
+juju scp --container jenkins ./jenkins_backup.tar.gz $JENKINS_UNIT:/jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT tar zxvf jenkins_backup.tar.gz
+juju ssh --container jenkins $JENKINS_UNIT chown -R jenkins:jenkins /backup
+juju ssh --container jenkins $JENKINS_UNIT cp -avR /backup/* /var/lib/jenkins
+juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
+```
+2. Restart pebble for the changes to take effect
+```bash
+juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
+```

docs/how-to/redeploy.md

@@ -0,0 +1,17 @@
+# How to redeploy Jenkins
+
+Redeployment is a process where the old charm instance is removed and data is migrated to a new charm instance. Redeploying the Jenkins charm consists of 3 steps:
+
+1. Create the new Jenkins charm instance
+```bash
+juju deploy jenkins-k8s jenkins-k8s-new
+```
+2. Migrate Jenkins data
+See the `Migrate Jenkins data` section below.
+3. Remove the old Jenkins charm instance
+```bash
+juju remove-application jenkins-k8s
+```
+
+### Migrate Jenkins data
+Follow the instructions in [the charm's documentation for backup and restore](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to migrate the data to the new Jenkins charm instance.

docs/how-to/resize-jenkins-storage.md

@@ -1,68 +1,17 @@
 # How to resize the jenkins-home storage volume
-The default size of the jenkins-home storage volume for a fresh installation is 1GB. While this works for most scenarios, operators might need to have more storage for installing plugins, storing artifacts, and runninng builds/checking out SCMs on the built-in node.
+The default size of the jenkins-home storage volume for a fresh installation is 1GB. While this works for most scenarios, operators might need to have more storage for installing plugins, storing artifacts, and running builds/checking out SCMs on the built-in node.
 
-A low disk-space on the built-in node will cause the node to go offline, blocking jenkins from running jobs.
+A low disk-space on the built-in node will cause the node to go offline, blocking Jenkins from running jobs.
 
-## Create a backup
-From [Backing-up/Restoring Jenkins](https://www.jenkins.io/doc/book/system-administration/backing-up/), This script backs up the most essential files as mentioned in the article:
-* The `master.key` file.
-* Job-related files in the `./jobs`, `./builds` and `./workspace` folders.
-* Plugins (`.hpi` and `.jpi` files) in the `./plugins` folder
+### Create a backup of the current Jenkins charm instance
+Follow the `Create a backup` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system
 
+### Deploy the new Jenkins charm instance, specifying the size of the storage volume
+Create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
 ```bash
-echo cat <<EOF > backup.sh
-#!/bin/bash
-export JENKINS_HOME=/var/lib/jenkins
-export JENKINS_BACKUP=/mnt/backup
-
-echo "running backup as \$(whoami) in \$(pwd)"
-mkdir -p \$JENKINS_BACKUP
-cp \$JENKINS_HOME/secrets/master.key \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/jobs \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/builds \$JENKINS_BACKUP
-cp -r \$JENKINS_HOME/workspace \$JENKINS_BACKUP
-mkdir -p \$JENKINS_BACKUP/plugins
-cp -r \$JENKINS_HOME/plugins/*.hpi \$JENKINS_BACKUP/plugins
-cp -r \$JENKINS_HOME/plugins/*.jpi \$JENKINS_BACKUP/plugins
-
-chown -R 2000:2000 $JENKINS_BACKUP
-tar zcvf jenkins_backup.tar.gz --directory=/mnt backup
-EOF
-
-chmod +x backup.sh
-```
-1. Transfer the backup script above to the running unit of the Jenkins-k8s charm and run it
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins ./backup.sh $JENKINS_UNIT:/backup.sh
-juju ssh  --container jenkins $JENKINS_UNIT /backup.sh
-```
-2. Retrieve the compressed backup file
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins $JENKINS_UNIT:/jenkins_backup.tar.gz jenkins_backup.tar.gz
-```
-3. With the data backed-up, we can remove the jenkins-k8s application.
-```bash
-JENKINS_APP=jenkins-k8s
-juju remove-application $JENKINS_APP
+juju deploy jenkins-k8s-new --storage jenkins-home=10GB
 ```
 
-## Restore the backup on a new charm instance
-1. When the application has been deleted, create a new application with the `--storage` flag. In this example we'll deploy the charm with a storage of 10GB
-```bash
-juju deploy jenkins-k8s --storage jenkins-home=10GB
-```
-2. Wait for the charm to be ready, then restore the backup on the new unit.
-```bash
-JENKINS_UNIT=jenkins-k8s/0
-juju scp --container jenkins ./jenkins_backup.tar.gz $JENKINS_UNIT:/jenkins_backup.tar.gz
-juju ssh --container jenkins $JENKINS_UNIT tar zxvf jenkins_backup.tar.gz
-juju ssh --container jenkins $JENKINS_UNIT chown -R jenkins:jenkins /backup
-juju ssh --container jenkins $JENKINS_UNIT cp -avR /backup/* /var/lib/jenkins
-juju ssh --container jenkins $JENKINS_UNIT rm -rf /backup /jenkins_backup.tar.gz
-```
-3. Finally restart pebble
-```bash
-juju ssh --container jenkins $JENKINS_UNIT pebble restart jenkins
-```
+### Restore the created backup onto the newly created Jenkins charm instance
+Follow the `Restore the backup on a new (or existing) charm instance` section of [the charm's backup and restore documentation](https://charmhub.io/jenkins-k8s/docs/backup-and-restore-jenkins) to create an archive of the Jenkins data on your host system. Remember to update the `JENKINS_UNIT` environment variable. For our example we have `JENKINS_UNIT=jenkins-k8s-new/0`
+

docs/reference/external-access.md

@@ -0,0 +1,19 @@
+# External access
+The Jenkins charm requires access to the following domains to install Jenkins and its plugins:
+
+* `jenkins-ci.org`
+* `updates.jenkins-ci.org`
+* `jenkins.io`
+* `updates.jenkins.io`
+* `.mirrors.jenkins-ci.org`
+* `fallback.get.jenkins.io`
+* `get.jenkins.io`
+* `pkg.jenkins.io`
+* `archives.jenkins.io`
+* `pkg.origin.jenkins.io`
+* `.mirrors.jenkins.io`
+* `www.jenkins.io`
+
+Depending on the localisation, some region-specific external mirrors might also be used. You can find more information on the [list of mirrors for Jenkins](https://get.jenkins.io/war/2.456/jenkins.war?mirrorstats).
+
+Some plugins can also require external access, such as `github.com` for the [Github branch source plugin](https://plugins.jenkins.io/github-branch-source/). Or an external Kubernetes cluster if you are using the [Kubernetes plugin](https://plugins.jenkins.io/kubernetes/). Refer to the documentation of the plugin for more details.

jenkins_rock/rockcraft.yaml

@@ -28,7 +28,7 @@ parts:
       mkdir -p $CRAFT_OVERLAY/var
       chmod 755 $CRAFT_OVERLAY/var
       groupadd -R $CRAFT_OVERLAY --gid 2000 jenkins
-      useradd -R $CRAFT_OVERLAY --system --gid 2000 --uid 2000 --home /srv/jenkins jenkins
+      useradd -R $CRAFT_OVERLAY --system --gid 2000 --uid 2000 --home /var/lib/jenkins jenkins
   jenkins:
     plugin: nil
     build-packages:

requirements.txt

@@ -1,6 +1,6 @@
 cosl==0.0.11
 jenkinsapi==0.3.13
-jsonschema==4.21.1
-ops==2.12.0
+jsonschema==4.22.0
+ops==2.13.0
 pydantic==1.10.15
-requests==2.31.0
+requests==2.32.2

src-docs/agent.py.md

@@ -12,22 +12,6 @@ The Jenkins agent relation observer.
 - **JENKINS_SERVICE_NAME**
 
 
----
-
-## <kbd>class</kbd> `AgentRelationData`
-Relation data required for adding the Jenkins agent. 
-
-
-
-**Attributes:**
-
- - <b>`url`</b>:  The Jenkins server url. 
- - <b>`secret`</b>:  The secret for agent node. 
-
-
-
-
-
 ---
 
 ## <kbd>class</kbd> `Observer`
@@ -39,7 +23,7 @@ The Jenkins agent relation observer.
 
  - <b>`agent_discovery_url`</b>:  external hostname to be passed to agents for discovery. 
 
-<a href="../src/agent.py#L39"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/agent.py#L27"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `__init__`
 
@@ -87,7 +71,7 @@ Shortcut for more simple access the model.
 
 ---
 
-<a href="../src/agent.py#L248"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/agent.py#L234"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `reconfigure_agent_discovery`
 

src-docs/charm.py.md

@@ -97,7 +97,7 @@ Return a dictionary for Jenkins Pebble layer.
 
 ---
 
-<a href="../src/charm.py#L175"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/charm.py#L178"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `jenkins_set_storage_config`
 

src-docs/ingress.py.md

@@ -49,7 +49,7 @@ Shortcut for more simple access the model.
 get_path() → str
 ```
 
-Return the path in whick Jenkins is expected to be listening. 
+Return the path in which Jenkins is expected to be listening. 
 
 
 

src/agent.py

@@ -17,18 +17,6 @@
 logger = logging.getLogger(__name__)
 
 
-class AgentRelationData(typing.TypedDict):
-    """Relation data required for adding the Jenkins agent.
-
-    Attributes:
-        url: The Jenkins server url.
-        secret: The secret for agent node.
-    """
-
-    url: str
-    secret: str
-
-
 class Observer(ops.Object):
     """The Jenkins agent relation observer.
 
@@ -146,9 +134,7 @@ def _on_deprecated_agent_relation_joined(self, event: ops.RelationJoinedEvent) -
             return
 
         jenkins_url = self.agent_discovery_url
-        event.relation.data[self.model.unit].update(
-            AgentRelationData(url=jenkins_url, secret=secret)
-        )
+        event.relation.data[self.model.unit].update({"url": jenkins_url, "secret": secret})
         self.charm.unit.status = ops.ActiveStatus()
 
     def _on_agent_relation_joined(self, event: ops.RelationJoinedEvent) -> None:

src/charm.py

@@ -171,6 +171,9 @@ def _upgrade_charm(self, event: ops.UpgradeCharmEvent) -> None:
         container = self.unit.get_container(JENKINS_SERVICE_NAME)
         if not jenkins.is_storage_ready(container):
             self.jenkins_set_storage_config(event)
+        # Update the agent discovery address.
+        # Updating the secret is not required since it's calculated using the agent's node name.
+        self.agent_observer.reconfigure_agent_discovery(event)
 
     def jenkins_set_storage_config(self, event: ops.framework.EventBase) -> None:
         """Correctly set permissions when storage is attached.

src/ingress.py

@@ -31,7 +31,7 @@ def __init__(self, charm: ops.CharmBase, key: str, relation_name: str):
         )
 
     def get_path(self) -> str:
-        """Return the path in whick Jenkins is expected to be listening.
+        """Return the path in which Jenkins is expected to be listening.
 
         Returns:
             the path for the ingress URL.

src/state.py

@@ -270,7 +270,7 @@ def from_charm(cls, charm: ops.CharmBase) -> "State":
             CharmIllegalNumUnitsError: if more than 1 unit of Jenkins charm is deployed.
         """
         try:
-            time_range_str = charm.config.get("restart-time-range")
+            time_range_str = typing.cast(str, charm.config.get("restart-time-range"))
             if time_range_str:
                 restart_time_range = Range.from_str(time_range_str)
             else:
@@ -301,7 +301,7 @@ def from_charm(cls, charm: ops.CharmBase) -> "State":
             logger.error("Invalid juju model proxy configuration, %s", exc)
             raise CharmConfigInvalidError("Invalid model proxy configuration.") from exc
 
-        plugins_str = charm.config.get("allowed-plugins")
+        plugins_str = typing.cast(str, charm.config.get("allowed-plugins"))
         plugins = (plugin.strip() for plugin in plugins_str.split(",")) if plugins_str else None
 
         if charm.app.planned_units() > 1:

tests/conftest.py

@@ -13,7 +13,7 @@ def pytest_addoption(parser: pytest.Parser):
         parser: pytest command line parser.
     """
     # The prebuilt charm file.
-    parser.addoption("--charm-file", action="store", default="")
+    parser.addoption("--charm-file", action="append", default=[])
     # The Jenkins image name:tag.
     parser.addoption("--jenkins-image", action="store", default="")
     # The path to kubernetes config.