diff --git a/docs/how-to/backup-and-restore-jenkins.md b/docs/how-to/backup-and-restore-jenkins.md index 2ca1f22d..50878dd1 100644 --- a/docs/how-to/backup-and-restore-jenkins.md +++ b/docs/how-to/backup-and-restore-jenkins.md @@ -1,4 +1,4 @@ -# Backup and restore Jenkins +# How to back up 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. diff --git a/docs/index.md b/docs/index.md index 3a6af82b..45929d2a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,12 +2,29 @@ A Juju charm deploying and managing Jenkins on Kubernetes. [Jenkins](https://www.jenkins.io/) is an open source automation server. Jenkins provides hundreds of plugins to support building, deploying and automating any project. It can be integrated with both k8s and machine (VM) agents for use. -This charm simplifies initial deployment and "day N" operations of Jenkins on Kubernetes, including integration with Jenkins agent instances, automatic patch updates and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings. - -As such, the charm makes it easy for those looking to take control of their own automation management system 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 on Kubernetes, including integration with Jenkins agent instances, automatic patch updates and more. It allows for deployment on many different Kubernetes platforms, from [MicroK8s](https://microk8s.io/) to [Charmed Kubernetes](https://ubuntu.com/kubernetes) to public cloud Kubernetes offerings. For DevOps or SRE teams this charm will make operating Jenkins simple and straightforward through Juju's clean interface. It will allow easy deployment into multiple environments for testing of changes, and supports scaling out agents for enterprise deployments. +## In this documentation + +| | | +|--|--| +| [Tutorials](https://charmhub.io/jenkins-k8s/docs/tutorial-getting-started)
Get started - a hands-on introduction to using the charm for new users
| [How-to guides](https://charmhub.io/jenkins-k8s/docs/how-to-configure-restart-time-range)
Step-by-step guides covering key operations and common tasks | +| [Reference](https://charmhub.io/jenkins-k8s/docs/reference-actions)
Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/jenkins-k8s/docs/explanation-agent-deprecated-relation)
Concepts - discussion and clarification of key topics | + +## Contributing to this documentation + +Documentation is an important part of this project, and we take the same open-source approach to the documentation as +the code. As such, we welcome community contributions, suggestions and constructive feedback on our documentation. +Our documentation is hosted on the [Charmhub forum](https://discourse.charmhub.io/) +to enable easy collaboration. Please use the "Help us improve this documentation" links on each documentation page to +either directly change something you see that's wrong, ask a question or make a suggestion about a potential change via +the comments section. + +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-k8s-operator/issues). + ## Project and community The Jenkins-k8s 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. @@ -15,7 +32,7 @@ The Jenkins-k8s Operator is a member of the Ubuntu family. It's an open source p - [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](Contribute) +- [Contribute](https://github.com/canonical/jenkins-k8s-operator/blob/94521d904be53c5645881fc43ba0b71ff60b9776/CONTRIBUTING.md) Thinking about using the Jenkins-k8s Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! @@ -24,8 +41,16 @@ Thinking about using the Jenkins-k8s Operator for your next project? [Get in tou 1. [Tutorial](tutorial) 1. [Getting Started](tutorial/getting-started.md) 1. [How to](how-to) + 1. [Backup and restore](how-to/backup-and-restore-jenkins.md) + 1. [Configure installable plugins](how-to/configure-installable-plugins.md) + 1. [Configure Jenkins memory usage](how-to/configure-jenkins-memory-usage.md) 1. [Configure restart-time-range](how-to/configure-restart-time-range.md) 1. [Get admin password](how-to/get-admin-password.md) + 1. [Integrate with external agents](how-to/integrate-with-external-agents.md) + 1. [Integrate with IAM](how-to/integrate-with-iam.md) + 1. [Integrate with machine agents](how-to/integrate-with-machine-agents.md) + 1. [Redeploy](how-to/redeploy.md) + 1. [Resize Jenkins storage](how-to/resize-jenkins-storage.md) 1. [Rotate credentials](how-to/rotate-credentials.md) 1. [Reference](reference) 1. [Actions](reference/actions.md) diff --git a/docs/reference/actions.md b/docs/reference/actions.md index 3c9809e4..7eb5acd1 100644 --- a/docs/reference/actions.md +++ b/docs/reference/actions.md @@ -1,3 +1,5 @@ # Actions See [Actions](https://charmhub.io/jenkins-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 index b5655b26..6e247cf9 100644 --- a/docs/reference/configurations.md +++ b/docs/reference/configurations.md @@ -1,3 +1,5 @@ # Configurations -See [Configure](https://charmhub.io/jenkins-k8s/configure). +See [Configurations](https://charmhub.io/jenkins-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 index 552724c0..23f2b9aa 100644 --- a/docs/reference/integrations.md +++ b/docs/reference/integrations.md @@ -2,33 +2,42 @@ ### agent -_Interface_: jenkins_agent_v0 +_Interface_: jenkins_agent_v0 _Supported charms_: [jenkins-agent-k8s](https://charmhub.io/jenkins-agent-k8s), [jenkins-agent](https://charmhub.io/jenkins-agent) 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. -Example agent relate command: `juju relate jenkins-k8s:agent jenkins-agent-k8s:agent` +Example agent integrate command: +``` +juju relate jenkins-k8s:agent jenkins-agent-k8s:agent +``` To create a [cross model relation](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` +``` +juju offer jenkins-agent:agent +``` Then, relate the offer from the k8s model where jenkins-k8s charm resides. -`juju relate jenkins-k8s:agent :/.jenkins-agent` +``` +juju integrate jenkins-k8s:agent :/.jenkins-agent +``` An example of such command would look like the following, using a jenkins-agent deployed on a localhost [lxd controller](https://juju.is/docs/olm/get-started-with-juju#heading--prepare-your-cloud). -`juju relate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent` +``` +juju integrate jenkins-k8s:agent localhost:admin/jenkins-vm-model.jenkins-agent +``` ### logging -_Interface_: loki_push_api +_Interface_: loki_push_api _Supported charms_: [loki-k8s](https://charmhub.io/loki-k8s) Logging relation provides a way to scrape logs produced from the Jenkins server charm. The Jenkins @@ -36,11 +45,14 @@ server logs are stored at `/var/lib/jenkins/logs/jenkins.log`. These logs are th emitted to the standard output. A promtail worker is spawned and will periodically push logs to Loki. -Example agent relate command: `juju relate jenkins-k8s:logging loki-k8s:logging` +Example agent integrate command: +``` +juju integrate jenkins-k8s:logging loki-k8s:logging +``` ### metrics-endpoint -_Interface_: prometheus_scrape +_Interface_: prometheus_scrape _Supported charms_: [prometheus-k8s](https://charmhub.io/prometheus-k8s) Metrics-endpoint relation allows scraping the `/prometheus` endpoint provided by Jenkins @@ -50,12 +62,14 @@ only be scraped by Prometheus once the relation becomes active. For more informa metrics exposed, please refer to the [`prometheus` plugin documentation](https://plugins.jenkins.io/prometheus/). -Example metrics-endpoint relate command: -`juju relate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint` +Example metrics-endpoint integrate command: +``` +juju integrate jenkins-k8s:metrics-endpoint prometheus-k8s:metrics-endpoint +``` ### grafana-dashboard -_Interface_: grafana_dashboard +_Interface_: grafana_dashboard _Supported charms_: [grafana-k8s](https://charmhub.io/grafana-k8s) Grafana-dashboard relation enables quick dashboard access already tailored to fit the needs of @@ -65,5 +79,11 @@ Performance and Health Overview” under the General section of the dashboard br (`/dashboards`). Modifications to the dashboard can be made but will not be persisted upon restart/redeployment of the charm. -Grafana-Prometheus relate command: `juju relate grafana-k8s:grafana-source prometheus-k8s:grafana-source` -Grafana-dashboard relate command: `juju relate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard` +Grafana-Prometheus integrate command: +``` +juju integrate grafana-k8s:grafana-source prometheus-k8s:grafana-source +``` +Grafana-dashboard integrate command: +``` +juju integrate jenkins-k8s:grafana-dashboard grafana-k8s:grafana-dashboard +```