Skip to content
This repository was archived by the owner on Nov 1, 2022. It is now read-only.

Commit

Permalink
Merge pull request #3102 from dholbach/update-docs
Browse files Browse the repository at this point in the history 
update theme/mkdocs, use note admonitions, fix identation
  • Loading branch information
Daniel Holbach authored Jun 3, 2020
2 parents b57f141 + 8f79802 commit 6ea97de
Show file tree
Hide file tree
Showing 15 changed files with 356 additions and 339 deletions.
15 changes: 8 additions & 7 deletions docs/contributing/building.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,13 +14,14 @@ make

This makes Docker images, and installs binaries to `$GOBIN` (if you define it) or `$(go env GOPATH)/bin`.

> **Note:** the default target architecture is amd64. If you would like
> to try to build Docker images and binaries for a different
> architecture you will have to set ARCH variable:
>
> ```sh
> $ make ARCH=<target_arch>
> ```
!!!note
The default target architecture is amd64. If you would like
to try to build Docker images and binaries for a different
architecture you will have to set ARCH variable:

```sh
$ make ARCH=<target_arch>
```

## Running tests

Expand Down
240 changes: 120 additions & 120 deletions docs/contributing/get-started-developing.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -87,9 +87,9 @@ and run what we have locally.
called [freshpod](https://github.com/GoogleCloudPlatform/freshpod)
that will be very useful to us later. You'll see. It's gonna be cool.
```sh
minikube addons enable freshpod
```
```sh
minikube addons enable freshpod
```
5. This part is really important. You're going to set some environment
variables which will intercept any images pulled by docker. Run
Expand All @@ -99,31 +99,31 @@ and run what we have locally.
will allow `minikube` to man-in-the-middle the requests Kubernetes
makes to pull images. It will look something like this:
```sh
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://192.168.99.128:2376"
export DOCKER_CERT_PATH="/home/fluxrulez/.minikube/certs"
export DOCKER_API_VERSION="1.35"
# Run this command to configure your shell:
# eval $(minikube docker-env)
```sh
export DOCKER_TLS_VERIFY="1"
export DOCKER_HOST="tcp://192.168.99.128:2376"
export DOCKER_CERT_PATH="/home/fluxrulez/.minikube/certs"
export DOCKER_API_VERSION="1.35"
# Run this command to configure your shell:
# eval $(minikube docker-env)
```
So, as the script suggests, run the following command:
So, as the script suggests, run the following command:
```sh
eval $(minikube docker-env)
```
```sh
eval $(minikube docker-env)
```
Now, be warned. These are local variables. This means that if you
run this `eval` in one terminal and then switch to another for later
when we build the Flux project, you're gonna hit some issues.
For one, you'll know it isn't working because Kubernetes will tell
you that it can't pull the image when you run `kubectl get pods`:
Now, be warned. These are local variables. This means that if you
run this `eval` in one terminal and then switch to another for later
when we build the Flux project, you're gonna hit some issues.
For one, you'll know it isn't working because Kubernetes will tell
you that it can't pull the image when you run `kubectl get pods`:
```sh
NAME READY STATUS RESTARTS AGE
flux-7f6bd57699-shx9v 0/1 ErrImagePull 0 35s
```
```sh
NAME READY STATUS RESTARTS AGE
flux-7f6bd57699-shx9v 0/1 ErrImagePull 0 35s
```
## Prepare the repository
Expand All @@ -132,97 +132,97 @@ and run what we have locally.
2. Clone `[email protected]:<YOUR-GITHUB-USERNAME>/flux.git` replacing
`<YOUR-GITHUB-USERNAME>` with your GitHub username.
In the same terminal you ran `eval $(minikube docker-env)`, run
`GO111MODULE=on go mod download` followed by `make` from the root
directory of the Flux repo. You'll see docker's usual output as it
builds the image layers. Once it's done, you should see something
like this in the middle of the output:
In the same terminal you ran `eval $(minikube docker-env)`, run
`GO111MODULE=on go mod download` followed by `make` from the root
directory of the Flux repo. You'll see docker's usual output as it
builds the image layers. Once it's done, you should see something
like this in the middle of the output:

```sh
Successfully built 606610e0f4ef
Successfully tagged docker.io/fluxcd/flux:latest
Successfully tagged docker.io/fluxcd/flux:master-a86167e4
```
```sh
Successfully built 606610e0f4ef
Successfully tagged docker.io/fluxcd/flux:latest
Successfully tagged docker.io/fluxcd/flux:master-a86167e4
```

This confirms that a new docker image was tagged for your image.
This confirms that a new docker image was tagged for your image.

3. Open up [`deploy/flux-deployment.yaml`](https://github.com/fluxcd/flux/blob/master/deploy/flux-deployment.yaml)
and update the image at `spec.template.spec.containers[0].image` to
be simply `docker.io/fluxcd/flux`. While we're here, also change
the `--git-url` to point towards your fork. It will look something
like this in the YAML:
```yaml
spec:
template:
spec:
```yaml
spec:
template:
spec:
containers:
- name: flux
image: docker.io/fluxcd/flux
imagePullPolicy: IfNotPresent
args:
- [email protected]:<YOUR-GITHUB-USERNAME>/flux-getting-started
- --git-branch=master
- name: flux
image: docker.io/fluxcd/flux
imagePullPolicy: IfNotPresent
args:
- [email protected]:<YOUR-GITHUB-USERNAME>/flux-getting-started
- --git-branch=master
```
4. We're ready to apply your newly-customized deployment! Since `kubectl`
will apply all the Kubernetes manifests it finds (recursively) in a
folder, we simply need to pass the directory to `kubectl apply`:

```sh
kubectl apply --filename ./deploy
````
```sh
kubectl apply --filename ./deploy
````
You should see an output similar to:
You should see an output similar to:
```sh
serviceaccount/flux created
clusterrole.rbac.authorization.k8s.io/flux created
clusterrolebinding.rbac.authorization.k8s.io/flux created
deployment.apps/flux created
secret/flux-git-deploy created
deployment.apps/memcached created
service/memcached created
secret/flux-git-deploy configured
```
```sh
serviceaccount/flux created
clusterrole.rbac.authorization.k8s.io/flux created
clusterrolebinding.rbac.authorization.k8s.io/flux created
deployment.apps/flux created
secret/flux-git-deploy created
deployment.apps/memcached created
service/memcached created
secret/flux-git-deploy configured
```

Congrats you just deployed your local Flux to your default namespace.
Check that everything is running:
Congrats you just deployed your local Flux to your default namespace.
Check that everything is running:

```sh
kubectl get pods --selector=name=flux
```
```sh
kubectl get pods --selector=name=flux
```

You should get an output that looks like:
You should get an output that looks like:

```sh
NAME READY STATUS RESTARTS AGE
flux-6f7fd5bbc-hpq85 1/1 Running 0 38s
```
```sh
NAME READY STATUS RESTARTS AGE
flux-6f7fd5bbc-hpq85 1/1 Running 0 38s
```

If (instead) you see that Ready is showing `0/1` and/or the status is
`ErrImagePull` double back on the instructions and make sure you did
everything correctly and in order.
If (instead) you see that Ready is showing `0/1` and/or the status is
`ErrImagePull` double back on the instructions and make sure you did
everything correctly and in order.

5. Pull the logs for your "fresh off of master" copy of Flux that you
just deployed locally to `minikube`:

```sh
kubectl logs --selector=name=flux
```
```sh
kubectl logs --selector=name=flux
```

You should see an output that looks something like this:
You should see an output that looks something like this:

```sh
ts=2019-02-28T18:58:45.091531939Z caller=warming.go:268 component=warmer info="refreshing image" image=docker.io/fluxcd/flux tag_count=60 to_update=60 of_which_refresh=0 of_which_missing=60
ts=2019-02-28T18:58:46.233723421Z caller=warming.go:364 component=warmer updated=docker.io/fluxcd/flux successful=60 attempted=60
ts=2019-02-28T18:58:46.234086642Z caller=images.go:17 component=sync-loop msg="polling images"
ts=2019-02-28T18:58:46.234125646Z caller=images.go:27 component=sync-loop msg="no automated services"
ts=2019-02-28T18:58:46.749598558Z caller=warming.go:268 component=warmer info="refreshing image" image=memcached tag_count=66 to_update=66 of_which_refresh=0 of_which_missing=66
ts=2019-02-28T18:58:51.017452675Z caller=warming.go:364 component=warmer updated=memcached successful=66 attempted=66
ts=2019-02-28T18:58:51.020061586Z caller=images.go:17 component=sync-loop msg="polling images"
ts=2019-02-28T18:58:51.020113243Z caller=images.go:27 component=sync-loop msg="no automated services"
```
```sh
ts=2019-02-28T18:58:45.091531939Z caller=warming.go:268 component=warmer info="refreshing image" image=docker.io/fluxcd/flux tag_count=60 to_update=60 of_which_refresh=0 of_which_missing=60
ts=2019-02-28T18:58:46.233723421Z caller=warming.go:364 component=warmer updated=docker.io/fluxcd/flux successful=60 attempted=60
ts=2019-02-28T18:58:46.234086642Z caller=images.go:17 component=sync-loop msg="polling images"
ts=2019-02-28T18:58:46.234125646Z caller=images.go:27 component=sync-loop msg="no automated services"
ts=2019-02-28T18:58:46.749598558Z caller=warming.go:268 component=warmer info="refreshing image" image=memcached tag_count=66 to_update=66 of_which_refresh=0 of_which_missing=66
ts=2019-02-28T18:58:51.017452675Z caller=warming.go:364 component=warmer updated=memcached successful=66 attempted=66
ts=2019-02-28T18:58:51.020061586Z caller=images.go:17 component=sync-loop msg="polling images"
ts=2019-02-28T18:58:51.020113243Z caller=images.go:27 component=sync-loop msg="no automated services"
```

## Make some changes

Expand All @@ -233,45 +233,45 @@ and run what we have locally.
by the name `execGitCmd`. Paste the following as the (new) first
line of the function:

```go
fmt.Println("executing git command ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ")
```
```go
fmt.Println("executing git command ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ")
```

2. Run `make` again. Once this finishes you can check on your running
pods with:

```sh
kubectl get pods --selector=name=flux
```

Keep your eye on the `AGE` column. It should be just a few seconds
old if you check out the `AGE` column:

```sh
NAME READY STATUS RESTARTS AGE
flux-6f7fd5bbc-6j9d5 1/1 Running 0 10s
```

This pod was deployed even though we didn't run any `kubectl`
commands or interact with Kubernetes directly because of the
`freshpod` `minikube` addon that we enabled earlier. Freshpod saw
that a new Docker image was tagged for `docker.io/fluxcd/flux:latest`
and it went ahead and redeployed that pod for us.

Consider that simply applying the `flux-deployment.yaml` file again
wouldn't do anything since the actual image we're targeting (which
is actually `docker.io/fluxcd/flux` with no `:latest` tag, but it's
the same difference) hasn't changed. The Kubernetes api server will
get that JSON request from `kubectl` and go: "right... so nothing has
changed in the file so I have nothing to do... IGNORE!".

There is another way to do this, of course. Remember that before when
we ran `make` that we did _also_ get an image tagged with the `:<branch>-<commit hash>`
syntax (in our specific example above it was `:master-a86167e4`).
We could, in theory, grab that tag every time we `make`, and then
paste it into `spec.template.spec.containers[0].image` of our
deployment. That's tedious and error prone. Instead, `freshpod` cuts
this step out for us and accomplishes the same end goal.
```sh
kubectl get pods --selector=name=flux
```

Keep your eye on the `AGE` column. It should be just a few seconds
old if you check out the `AGE` column:

```sh
NAME READY STATUS RESTARTS AGE
flux-6f7fd5bbc-6j9d5 1/1 Running 0 10s
```

This pod was deployed even though we didn't run any `kubectl`
commands or interact with Kubernetes directly because of the
`freshpod` `minikube` addon that we enabled earlier. Freshpod saw
that a new Docker image was tagged for `docker.io/fluxcd/flux:latest`
and it went ahead and redeployed that pod for us.
Consider that simply applying the `flux-deployment.yaml` file again
wouldn't do anything since the actual image we're targeting (which
is actually `docker.io/fluxcd/flux` with no `:latest` tag, but it's
the same difference) hasn't changed. The Kubernetes api server will
get that JSON request from `kubectl` and go: "right... so nothing has
changed in the file so I have nothing to do... IGNORE!".
There is another way to do this, of course. Remember that before when
we ran `make` that we did _also_ get an image tagged with the `:<branch>-<commit hash>`
syntax (in our specific example above it was `:master-a86167e4`).
We could, in theory, grab that tag every time we `make`, and then
paste it into `spec.template.spec.containers[0].image` of our
deployment. That's tedious and error prone. Instead, `freshpod` cuts
this step out for us and accomplishes the same end goal.

3. Check the logs again (with `kubectl logs --selector=name=flux`) to
find that your obnoxious chain of `Z`s is present.
Expand Down
41 changes: 21 additions & 20 deletions docs/guides/provide-own-ssh-key.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,28 +9,29 @@ creating the configured secret in the expected format.

1. create a Kubernetes secret from your own private key:

```sh
kubectl create secret generic flux-git-deploy --from-file=identity=/full/path/to/private_key
```

this will result in a secret that has the structure:

```yaml
apiVersion: v1
data:
identity: <base64 encoded RSA PRIVATE KEY>
kind: Secret
type: Opaque
metadata:
...
```
```sh
kubectl create secret generic flux-git-deploy --from-file=identity=/full/path/to/private_key
```
this will result in a secret that has the structure:
```yaml
apiVersion: v1
data:
identity: <base64 encoded RSA PRIVATE KEY>
kind: Secret
type: Opaque
metadata:
...
```

2. _(optional)_ if you created the secret with a non-default name
(default: `flux-git-deploy`), set the `--k8s-secret-name` flag to
the name of your secret (i.e. `--k8s-secret-name=foo`).

> **Note:** the SSH key must be configured to have R/W access to the
> repository. More specifically, the SSH key must be able to create
> and update tags. E.g. in Gitlab, that means it requires `Maintainer`
> permissions. The `Developer` permission can create tags, but not
> update them.
!!!note
The SSH key must be configured to have R/W access to the
repository. More specifically, the SSH key must be able to create
and update tags. E.g. in Gitlab, that means it requires `Maintainer`
permissions. The `Developer` permission can create tags, but not
update them.
Loading

0 comments on commit 6ea97de

Please sign in to comment.