Jenkins agent minimal working charm (#4)

Minimal jenkins agent charm
---------

Co-authored-by: arturo-seijas <[email protected]>
Co-authored-by: Yanks Yoon <[email protected]>

.github/workflows/integration_test.yaml

@@ -7,17 +7,11 @@ jobs:
   integration-tests:
     uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main
     secrets: inherit
+    permissions:
+      contents: read
+      packages: write
     with:
-      chaos-app-label: app.kubernetes.io/name=indico
-      chaos-enabled: false
-      chaos-experiments: pod-delete
-      load-test-enabled: false
-      load-test-run-args: "-e LOAD_TEST_HOST=localhost"
-      zap-before-command: "curl -H \"Host: indico.local\" http://localhost/bootstrap --data-raw 'csrf_token=00000000-0000-0000-0000-000000000000&first_name=admin&last_name=admin&email=admin%40admin.com&username=admin&password=lunarlobster&confirm_password=lunarlobster&affiliation=Canonical'"
-      zap-enabled: true
-      zap-cmd-options: '-T 60 -z "-addoninstall jython" --hook "/zap/wrk/tests/zap/hook.py"'
-      zap-target: localhost
-      zap-target-port: 80
-      zap-rules-file-name: "zap_rules.tsv"
-      trivy-fs-enabled: true
-      trivy-image-config: "trivy.yaml"
+      pre-run-script: |
+        -c "sudo microk8s config > ${GITHUB_WORKSPACE}/kube-config
+        chmod +x tests/integration/pre_run_script.sh
+        ./tests/integration/pre_run_script.sh"

.gitignore

@@ -10,3 +10,8 @@ __pycache__/
 .mypy_cache
 *.egg-info/
 */*.rock
+*/*.snap
+# charmcraft-related directories
+prime/
+parts/
+stage/

.licenserc.yaml

@@ -0,0 +1,36 @@
+header:
+  license:
+    spdx-id: Apache-2.0
+    copyright-owner: Canonical Ltd.
+    content: |
+      Copyright [year] [owner]
+      See LICENSE file for licensing details.
+  paths:
+    - '**'
+  paths-ignore:
+    - '.github/**'
+    - '**/.gitkeep'
+    - '**/*.cfg'
+    - '**/*.conf'
+    - '**/*.j2'
+    - '**/*.json'
+    - '**/*.md'
+    - '**/*.rule'
+    - '**/*.tmpl'
+    - '**/*.txt'
+    - '.codespellignore'
+    - '.dockerignore'
+    - '.flake8'
+    - '.jujuignore'
+    - '.gitignore'
+    - '.licenserc.yaml'
+    - '.trivyignore'
+    - '.woke.yaml'
+    - '.woke.yml'
+    - 'CODEOWNERS'
+    - 'icon.svg'
+    - 'LICENSE'
+    - 'trivy.yaml'
+    - 'zap_rules.tsv'
+    - 'lib/**'
+  comment: on-failure

.woke.yaml

@@ -0,0 +1,10 @@
+ignore_files:
+  - lib/*
+
+rules:
+  # [2022.11.28] Ignore "slave"/"master" - The relation with Jenkins charm is using this
+  # terminology due to support for older versions of Jenkins.
+  - name: slave
+  - name: master
+  # Ignore whitelist - we are using it to ignore pydantic in pyptoject.toml
+  - name: whitelist

charmcraft.yaml

@@ -6,8 +6,10 @@
 type: charm
 bases:
   - build-on:
-    - name: ubuntu
-      channel: "22.04"
+      - name: ubuntu
+        channel: "22.04"
     run-on:
-    - name: ubuntu
-      channel: "22.04"
+      - name: ubuntu
+        channel: "20.04"
+      - name: ubuntu
+        channel: "22.04"

config.yaml

@@ -1,16 +1,9 @@
 # Copyright 2024 Canonical Ltd.
 # See LICENSE file for licensing details.
-# This file defines charm config options, and populates the Configure tab on Charmhub.
-# If your charm does not require configuration options, delete this file entirely.
-#
-# See https://juju.is/docs/config for guidance.
-
 options:
-  # An example config option to customise the log level of the workload
-  log-level:
-    description: |
-      Configures the log level of gunicorn. 
-
-      Acceptable values are: "info", "debug", "warning", "error" and "critical"
-    default: "info"
+  jenkins_agent_labels:
     type: string
+    default: ""
+    description: |
+      Comma-separated list of labels to be assigned to the agent in Jenkins. If not set it will
+      default to the agents hardware identifier, e.g.: 'x86_64'

docs/explanation/workload.md

@@ -0,0 +1,22 @@
+# Managing workload inside the charm
+The core jenkins agent workload requires 3 main parameters (JENKINS_URL, JENKINS_AGENT and JENKINS_SECRET) and is defined as a 2-step process:
+
+1. Download the agent binary at JENKINS_URL/jnlpJars/agent.jar and store it in the agent’s home directory
+2. Run the agent binary with the following parameters to register the node with Jenkins
+```
+/usr/bin/java -jar agent.jar \\
+-jnlpUrl "<jnlp-path-on-jenkins-server>" \\
+-workDir "${JENKINS_WORKDIR}" \\
+-noReconnect \\
+-secret "${JENKINS_SECRET}"
+```
+In the charm, this workload is managed using an [apt package](https://launchpad.net/~canonical-is-devops/+archive/ubuntu/jenkins-agent-charm) which installs a systemd service that can be configured via a configuration file.
+```
+# File: /etc/systemd/system/jenkins-agent.service.d/override.conf
+[Service]
+Environment="JENKINS_SECRET=secret"
+Environment="JENKINS_URL=url"
+Environment="JENKINS_AGENT=node-name"
+```
+
+The service won’t start automatically through the use of the `--no-start` option during packaging in order to allow flexibility between running the workload as a service and as a standalone executable, located at `/usr/bin/jenkins-agent`.

docs/how-to/configure-agent-node-label.md

@@ -0,0 +1,10 @@
+# How to configure installable plugins
+
+### Configure `jenkins_agent_labels`
+
+Use the `jenkins_agent_labels` configuration to allow assigning different labels to the agent's node on the jenkins server.
+Comma-separated list of node labels. If empty, the agent's node will have the underlying machine's arch as a label by default, most of the time this will be `x86_64`. If this value is configured before any integrations with the jenkins charm is established, the label will be applied during the node's creation once an integration has been established.
+
+```
+juju config jenkins-agent jenkins_agent_labels=label1,label2,label3
+```

docs/index.md

@@ -0,0 +1,32 @@
+# Jenkins-k8s Operator
+
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing [Jenkins](https://www.jenkins.io/) Agent on machines and configurable to use a Jenkins charm deployed in another Juju model.
+
+This charm simplifies initial deployment and "day N" operations of Jenkins Agent on VMs and bare metal.
+
+As such, the charm makes it easy for those looking to take control of their own agents whilst keeping operations simple, and gives them the freedom to deploy on the platform of their choice.
+
+For DevOps or SRE teams this charm will make operating Jenkins Agent simple and straightforward through Juju's clean interface. It will allow easy deployment into multiple environments for testing changes, and supports scaling out for enterprise deployments.
+
+## Project and community
+
+The Jenkins-agent Operator is a member of the Ubuntu family. It's an open source project that warmly welcomes community projects, contributions, suggestions, fixes and constructive feedback.
+
+- [Code of conduct](https://ubuntu.com/community/code-of-conduct)
+- [Get support](https://discourse.charmhub.io/)
+- [Join our online chat](https://app.element.io/#/room/#charmhub-charmdev:ubuntu.com)
+- [Contribute](Contribute)
+
+Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://app.element.io/#/room/#charmhub-charmdev:ubuntu.com)!
+
+# Contents
+
+1. [Tutorial](tutorial)
+   1. [Getting Started](tutorial/getting-started.md)
+1. [How to](how-to)
+   1. [Configure agent node label](how-to/configure-agent-node-label.md)
+1. [Reference](reference)
+   1. [Actions](reference/actions.md)
+   1. [Configurations](reference/configurations.md)
+   1. [Integrations](reference/integrations.md)
+1. [Explanation](explanation)

docs/reference/actions.md

@@ -0,0 +1,3 @@
+# Actions
+
+See [Actions](https://charmhub.io/jenkins-agent/actions).

docs/reference/configurations.md

@@ -0,0 +1,3 @@
+# Configurations
+
+See [Configure](https://charmhub.io/jenkins-agent/configure).

docs/reference/integrations.md

@@ -0,0 +1,21 @@
+# Integrations
+
+### agent
+
+_Interface_: jenkins_agent_v0
+_Supported charms_: [jenkins-k8s](https://charmhub.io/jenkins-agent-k8s),
+
+Jenkins agents provide a way to perform tasks scheduled by the Jenkins server. Jenkins agents are
+used to distribute workload across multiple containers, allowing parallel execution of jobs.
+
+To create a [cross model integration](https://juju.is/docs/olm/manage-cross-model-integrations) with
+a jenkins-agent (VM) charm, create an offer from the machine model.
+
+`juju offer jenkins-agent:agent`
+
+Then, integrate the offer from the k8s model where jenkins-k8s charm resides.
+
+`juju integrate jenkins-k8s:agent <controller-name>:<juju-user>/<agent-model>.jenkins-agent`
+
+An example of such command would look like the following, using a jenkins-k8s charm deployed on microk8s.
+`juju integrate jenkins-k8s:agent localhost:admin/jenkins-agent-model.jenkins-agent`

docs/tutorial/getting-started.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+## What you'll do
+
+- Deploy the [jenkins-agent charm](https://charmhub.io/jenkins-agent)
+- Deploy the [jenkins-k8s charm](https://charmhub.io/jenkins-k8s) and integrate with it via a cross-model integration
+
+The `jenkins-agent` charm helps deploy a Jenkins agent with ease and also helps operate the charm. This
+tutorial will walk you through each step of deployment to get a basic Jenkins agent deployment and integrate it with Jenkins.
+
+### Prerequisites
+
+To deploy the `jenkins-agent` charm, you'll need to have a bootstrapped machine model. Learn about
+bootstrapping different clouds [here](https://juju.is/docs/olm/get-started-with-juju#heading--prepare-your-cloud).
+
+Use `juju bootstrap localhost localhost` to bootstrap a `lxd` machine controller with the name
+`localhost` for tutorial purposes.
+
+### Setting up the tutorial model
+
+To easily clean up the resources and to separate your workload from the contents of this tutorial,
+it is recommended to set up a new model with the following command.
+
+```
+juju add-model tutorial
+```
+
+### Deploy the jenkins-agent charm
+
+Start off by deploying the jenkins-agent charm. By default it will deploy the latest stable release
+of the jenkins-agent charm.
+
+```
+# Deploy an edge version of the charm until stable version is released.
+juju deploy jenkins-agent --channel=latest/edge
+```
+
+### Deploy and integrate with the jenkins-k8s charm
+
+To deploy jenkins-k8s charm, you will need a juju bootstrapped with any kubernetes controller.
+To see how to bootstrap your juju installation with microk8s, please refer to the documentation
+on microk8s [installation](https://juju.is/docs/olm/microk8s).
+
+Use `juju bootstrap microk8s localhost-microk8s` to bootstrap a `microk8s` machine controller with the name
+`localhost-microk8s` for tutorial purposes.
+
+Then, switch to your kubernetes controller add a model for the jenkins-k8s charm with the following command:
+```
+juju switch -c localhost-microk8s
+juju add-model jenkins-tutorial
+```
+
+Continue by deploying the jenkins-k8s charm. by default it will deploy the latest stable release of the jenkins-k8s charm:
+```
+juju deploy jenkins-k8s --channel=latest/edge
+```
+
+The Jenkins application can only have a single server unit. Adding more units through --num-units parameter will cause the application to misbehave.
+
+#### Create an offer for Cross Model Integration
+
+To integrate charms
+[across different models](https://juju.is/docs/juju/manage-cross-model-integrations), a juju
+[`offer`](https://juju.is/docs/juju/manage-cross-model-integrations#heading--create-an-offer) is
+required.
+
+Create an offer of the `jenkins-k8s` charm's `agent` integration.
+
+```
+juju offer jenkins-k8s:agent
+```
+
+The output should look similar to the contents below:
+
+```
+Application "jenkins-k8s" endpoints [agent] available at "admin/jenkins-tutorial.jenkins-k8s"
+```
+
+#### Integrate the Jenkins agent charm through the offer
+
+Switch back to the k8s model where the `jenkins-agent` charm is deployed. An example of the switch
+command looks like the following: `juju switch localhost:tutorial`.
+
+Integrate the `jenkins-agent` charm to the `jenkins-k8s` server charm through the offer.
+The syntax of the offer is as follows: `<controller>:<user>/<model>.<charm>`.
+
+```
+juju integrate jenkins-agent:agent localhost-microk8s:admin/jenkins-tutorial.jenkins-agent
+```
+
+
+### Cleaning up the environment
+
+Congratulations! You have successfully finished the tutorial. You can now remove the
+models that you’ve created using the following command.
+
+```
+juju destroy model localhost-microk8s:admin/jenkins-tutorial -y --release-storage
+juju destroy model localhost:admin/tutorial -y --release-storage
+```