Update docs (#50)

* Update getting-started.md As the Jenkins tutorials were condensed into one, update this file to point to the full tutorial. * Update index.md (ISD-2291) Adopt template landing page: - Removed jargon from overview section - Added "project and community" section - Updated links * Update order of Contents section (ISD-2323) * Update contents section (ISD-2298) Update the how-to page title to follow the convention laid out in the style guide * Update actions.md (ISD-2304) Add link to Juju docs * Update configurations.md (ISD-2304) - "Configure" --> "Configurations" - Add link to Juju docs * Update integrations.md (ISD-2318) Put example command in command block * Junkins --> Jenkins * update trivyignore --------- Co-authored-by: Arturo Seijas <arturo.seijas@canonical.com>
canonical · Oct 3, 2024 · 050c531 · 050c531
1 parent 9b7b145
commit 050c531
Show file tree

Hide file tree

Showing 6 changed files with 35 additions and 72 deletions.
diff --git a/.trivyignore b/.trivyignore
@@ -1,2 +1,4 @@
 CVE-2023-45288
 CVE-2024-24790
+CVE-2024-34156
+
diff --git a/docs/index.md b/docs/index.md
@@ -1,8 +1,8 @@
-A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing [Jenkins](https://www.jenkins.io/) agents on Kubernetes, configurable to use a Jenkins charm deployed in another Juju model, or to connect to a standalone Jenkins instance.
+# Jenkins Agent K8s Operator
 
-This charm simplifies initial deployment and "day N" operations of Jenkins agent on Kubernetes. It allows for deployment on many  different Kubernetes platforms, from [MicroK8s](https://microk8s.io) to [Charmed Kubernetes](https://ubuntu.com/kubernetes/charmed-k8s) and public cloud Kubernetes offerings.
+A [Juju](https://juju.is/) [charm](https://juju.is/docs/olm/charmed-operators) deploying and managing [Jenkins](https://www.jenkins.io/) agents on Kubernetes. This charm is configurable to use with a Jenkins charm deployed in another Juju model, or to connect to a standalone Jenkins instance.
 
-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 Kubernetes platform of their choice.
+This charm simplifies initial deployment and operations of Jenkins agents on Kubernetes. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io) to [Charmed Kubernetes](https://ubuntu.com/kubernetes/charmed-k8s) and public cloud Kubernetes offerings.
 
 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.
 
@@ -20,15 +20,28 @@ Documentation is an important part of this project, and we take the same open-so
 
 If there's a particular area of documentation that you'd like to see that's missing, please [file a bug](https://github.com/canonical/jenkins-agent-k8s-operator/issues).
 
+## Project and community
+
+The jenkins-agent-k8s charm 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://matrix.to/#/#charmhub-charmdev:ubuntu.com)
+- [Contribute](https://github.com/canonical/jenkins-agent-k8s-operator/blob/9b7b1452328b185d0149eedde29e5746b057893b/CONTRIBUTING.md)
+
+Thinking about using the jenkins-agent-k8s charm for your next project? 
+[Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
+
 # Contents
 
-1. [Explanation](explanation)
-  1. [Charm architecture](explanation/charm-architecture.md)
+1. [Tutorial](tutorial)
+  1. [Quick guide](tutorial/getting-started.md)
 1. [How To](how-to)
-  1. [How to contribute](how-to/contribute.md)
+  1. [Contribute](how-to/contribute.md)
 1. [Reference](reference)
   1. [Actions](reference/actions.md)
   1. [Configurations](reference/configurations.md)
   1. [Integrations](reference/integrations.md)
-1. [Tutorial](tutorial)
-  1. [Quick guide](tutorial/getting-started.md)
+1. [Explanation](explanation)
+  1. [Charm architecture](explanation/charm-architecture.md)
diff --git a/docs/reference/actions.md b/docs/reference/actions.md
@@ -1,3 +1,5 @@
 # Actions
 
-See [Actions](https://charmhub.io/jenkins-agent-k8s/actions).
+See [Actions](https://charmhub.io/jenkins-agent-k8s/actions).
+
+> Read more about actions in the Juju docs: [Action](https://juju.is/docs/juju/action)
diff --git a/docs/reference/configurations.md b/docs/reference/configurations.md
@@ -1,3 +1,5 @@
 # Configurations
 
-See [Configure](https://charmhub.io/jenkins-agent-k8s/configure).
+See [Configurations](https://charmhub.io/jenkins-agent-k8s/configure).
+
+> Read more about configurations in the Juju docs: [Configuration](https://juju.is/docs/juju/configuration)
diff --git a/docs/reference/integrations.md b/docs/reference/integrations.md
@@ -7,4 +7,7 @@ _Supported charms_: [jenkins](https://charmhub.io/jenkins)
 
 Agent integration is a required relation for the Jenkins agent charm to supply the job execution output to Jenkins.
 
-Example agent integrate command: `juju integrate jenkins jenkins-agent-k8s`
+Example agent integrate command: 
+```
+juju integrate jenkins jenkins-agent-k8s
+```
diff --git a/docs/tutorial/getting-started.md b/docs/tutorial/getting-started.md
@@ -1,62 +1,3 @@
-# Quick guide
+# Deploy the jenkins-agent-k8s-operator charm for the first time
 
-## What you’ll do
-
-- Deploy the [Jenkins agent k8s charm](https://charmhub.io/jenkins-agent-k8s).
-- Integrate with [the Jenkins charm](https://charmhub.io/jenkins)
-
-Through the process, you'll inspect the Kubernetes resources created and verify the workload state.
-
-## Requirements
-
-- Juju 3 installed.
-- Juju controller and model created.
-
-For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
-
-### Deploy the Jenkins agent k8s charm
-
-Since the Jenkins agent k8s charm requires a connection to Jenkins, you'll deploy the Jenkins charm too. For more information, see [Charm Architecture](https://charmhub.io/jenkins-agent-k8s/docs/explanation-charm-architecture).
-
-
-Deploy the charms:
-
-```bash
-juju deploy jenkins-agent-k8s
-juju deploy jenkins-k8s
-```
-
-To see the pod created by the Jenkins agent k8s charm, run `kubectl get pods` on a namespace named for the Juju model you've deployed the charm into. The output is similar to the following:
-
-```bash
-NAME                             READY   STATUS            RESTARTS   AGE
-jenkins-agent-k8s-0              2/2     Running           0          2m2s
-```
-
-Run [`juju status`](https://juju.is/docs/olm/juju-status) to see the current status of the deployment. In the Unit list, you can see that Jenkins agent k8s is waiting:
-
-```bash
-jenkins-agent-k8s/0*  blocked   idle   10.1.180.75         Waiting for config/relation.
-```
-
-This means that Jenkins k8s agent charm isn't integrated with Jenkins yet.
-
-### Integrate with the Jenkins charm
-
-Provide integration between Jenkins agent k8s and Jenkins by running the following [`juju integrate`](https://juju.is/docs/juju/juju-integrate) command:
-
-```bash
-juju integrate jenkins-k8s jenkins-agent-k8s
-```
-
-Run `juju status` and wait until the Application status is `Active` as the following example:
-
-Optional: run `juju status --relations --watch 5s` to watch the status every 5 seconds with the Relations section.
-
-```bash
-App                Version  Status   Scale  Charm              Channel  Rev  Address         Exposed  Message
-jenkins-agent-k8s           active       1  jenkins-agent-k8s  stable    18  10.152.183.135  no       
-
-```
-
-The deployment finishes when the status shows "Active".
+See the [full Jenkins tutorial](https://charmhub.io/jenkins-k8s/docs/tutorial-getting-started) in the jenkins-k8s-operator documentation.