Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Try 1 to improve tutorial #195

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Try 1 to improve tutorial #195

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
129 changes: 104 additions & 25 deletions docs/tutorial/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,27 +1,32 @@
# Getting Started
# Deploy the jenkins-k8s charm for the first time

## What you'll do
## What we do

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I actually think it's fine to leave this as "What you'll do", at least for now to remain consistent with the other tutorials. (We can revisit down the line)

- Deploy the [jenkins-k8s charm](https://charmhub.io/jenkins-k8s)
- Access the UI
- Deploy and integrate agents
- Get admin password

The jenkins-k8s charm helps deploy a Jenkins automation server application with ease and
also helps operate the charm. This
tutorial will walk you through each step of deployment to get a basic Jenkins server deployment.
tutorial will walk through each step of deployment to get a basic Jenkins server deployment.

### Prerequisites
### Requirements

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).
- A machine with amd64 architecture.
- Juju 3 installed.
- Juju MicroK8s controller created and active named microk8s. [MetalLB addon](https://microk8s.io/docs/addon-metallb) should be enabled for traefik-k8s to work.
- LXD controller created and active named lxd (optional).
- All the requirements can be met using the [Multipass charm-dev blueprint](https://juju.is/docs/juju/set-up--tear-down-your-test-environment#heading--set-up---tear-down-automatically). Use the Multipass VM shell to run all commands in this tutorial.

For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).

### Set up the tutorial model

To easily clean up the resources and to separate your workload from the contents of this tutorial,
set up a new Juju model with the following command.
set up a new Juju model in the microk8s controller with the following command.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: microk8s --> MicroK8s
or
microk8s --> microk8s (if you're referring to the name of the controller)

```
juju switch microk8s
juju add-model jenkins-tutorial
```

Expand All @@ -31,34 +36,59 @@ Start off by deploying the jenkins-k8s charm. By default it will deploy the late
of the jenkins-k8s charm.

```
# Deploy an edge version of the charm until stable version is released.
juju deploy jenkins-k8s --channel=latest/edge
```

Wait for it to be active:
```
Copy link
Contributor

@erinecon erinecon Sep 27, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: Wait for it to be active: --> Wait for the charm to become active:

juju wait-for application jenkins-k8s
```

The Jenkins application can only have a single server unit. Adding more units through `--num-units`
parameter will cause the application to misbehave.

### Deploy and integrate agents

By default, jenkins-k8s server application is installed with 0 executors for security purposes.
A functional Jenkins application requires additional Jenkins agents to be integrated.
### Expose jenkins-k8s through ingress

The following commands deploy 3 units of the jenkins-agent-k8s charm and integrate them with the
jenkins-k8s charm.
Deploy traefik-k8s charm and integrate it with the jenkins-k8s charm:
```
juju deploy traefik-k8s --channel=latest/edge --trust
juju integrate jenkins-k8s:ingress traefik-k8s
```

You can check the state with:
```
juju status --relations
```
juju deploy jenkins-agent-k8s --channel=latest/edge --num-units=3
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe at this point say that the deployment is finished when all the units are in "active" status


# 'agent' relation name is required since jenkins-k8s charm provides multiple compatible
# interfaces with jenkins-agent-k8s charm.
juju relate jenkins-k8s:agent jenkins-agent-k8s:agent

After a few minutes, you can get the url to connect to.
```
juju run traefik-k8s/0 show-proxied-endpoints --format=yaml
```

The output will be something similar to:
```
Running operation 1 with 1 task
- task 2 on unit-traefik-k8s-0

### Get admin credentials
Waiting for task 2...
traefik-k8s/0:
id: "2"
results:
proxied-endpoints: '{"traefik-k8s": {"url": "http://10.12.97.102"}, "jenkins-k8s":
{"url": "http://10.12.97.102/jenkins-tutorial-jenkins-k8s"}}'
return-code: 0
status: completed
timing:
completed: 2024-09-27 15:09:36 +0200 CEST
enqueued: 2024-09-27 15:09:35 +0200 CEST
started: 2024-09-27 15:09:35 +0200 CEST
unit: traefik-k8s/0
```

You can access the Jenkins server application UI by accessing the IP of a jenkins-k8s unit. To
start managing Jenkins server as an administrator, you need to get the password for the admin
account.
In this case, the url to use in your browser will be `http://10.12.97.102/jenkins-tutorial-jenkins-k8s`. In
your case it will probably be a different IP address.

By running the `get-admin-password` action on a jenkins-k8s unit, juju will read and fetch the
admin credentials setup for you. You can use the following command below.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: Capitalise Juju

Expand All @@ -82,14 +112,63 @@ unit-jenkins-k8s-0:
started: <timestamp>
```

You can now access your Jenkins server UI at `http://<UNIT_IP>:8080` and login using username
"admin" and password from the action above.
You can now access your Jenkins server UI at the previous url, and login using username "admin" and password from the action above.

### Deploy and integrate k8s agents

By default, jenkins-k8s server application is installed with 0 executors for security purposes.
A functional Jenkins application requires additional Jenkins agents to be integrated.

The following commands deploy 3 units of the jenkins-agent-k8s charm and integrate them with the
jenkins-k8s charm.

```
juju deploy jenkins-agent-k8s --channel=latest/edge --num-units=3

# 'agent' relation name is required since jenkins-k8s charm provides multiple compatible
# interfaces with jenkins-agent-k8s charm.
juju integrate jenkins-k8s:agent jenkins-agent-k8s:agent
```

### Deploy and integrate machine agents (optional)

For this section you need a machine model named `lxd`.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention that the Multipass blueprint will automatically set up the machine model for you

The first requirement is to create the offer, so the jenkins-k8s agent endpoint is available
for cross-model integrations.

```
juju offer jenkins-k8s:agent
```

Once the offer is created, we can create the new model, deploy the machine jenkins-agent charm
and integrate it with jenkins-k8s with:
```
juju add-model --controller=lxd jenkins-tutorial
juju deploy --model lxd:jenkins-tutorial jenkins-agent --channel=latest/edge
juju integrate --model lxd:jenkins-tutorial jenkins-agent:agent microk8s:admin/jenkins-tutorial.jenkins-k8s
```

You can check the status of the lxd model with:
```
juju status --model lxd:jenkins-tutorial --relations
```

After a few minutes you should be able to see the jenkins agent machine model as a new build executor
in the Jenkins UI.


### Cleaning up the environment

Congratulations! You have successfully finished the jennkins-k8s tutorial. You can now remove the
model environment that you’ve created using the following command.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpick: We set up two different environments (assuming the user followed the optional part), so probably should say "You can now remove the model environments..."


```
juju destroy-model lxd:jenkins-tutorial --destroy-storage
```

```
juju destroy-model jenkins-tutorial --destroy-storage
```

Loading