Skip to content

Commit

Permalink
doc: add tutorial document
Browse files Browse the repository at this point in the history
Change:
- Move the quick start from README to `docs/tutorial`.

Signed-off-by: Yadong Ding <ding_yadong@foxmail.com>
  • Loading branch information
Desiki-high committed Sep 6, 2023
1 parent a7aa579 commit 2a0b71c
Show file tree
Hide file tree
Showing 2 changed files with 123 additions and 113 deletions.
117 changes: 4 additions & 113 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,115 +4,11 @@ Acceleration Service provides a general service to Harbor with the ability to au

⚠️ This project is still in progress, see more details in this [proposal](https://github.com/goharbor/community/pull/167).

## Quickstart

### Build binary

``` shell
$ make
```

### Configuration (Harbor side)

Login to Harbor web interface to complete the following operation.

1. Add webhook configuration

Projects -> Webhooks -> `+ NEW WEBHOOK`, add webhook configuration with following fields:

- Notify Type: http
- Event Type: artifact pushed
- Endpoint URL: `<acceleration service address>`/api/v1/conversions
- Auth Header: `<configured in acceleration service>`

2. Add robot account

Administration -> Robot Accounts -> `+ NEW ROBOT ACCOUNT`, add robot account with following fields:

- Expiration time: `<by your choice>`
- Reset permissions: select `Push Artifact`, `Pull Artifact`, `Create Tag`

Generate a base64 encoded auth string using robot account name and secret like this:

``` shell
$ printf '<robot-name>:<robot-secret>' | base64
```

### Configuration (Acceleration service side)

1. Copy template config file

nydus:

``` shell
$ cp misc/config/config.nydus.yaml misc/config/config.yaml
```

estargz:

``` shell
$ cp misc/config/config.estargz.yaml misc/config/config.yaml
```

2. Edit config file

Following comments in `misc/config/config.yaml`, ensure base64 encoded auth string and webhook auth header be configured correctly.

### Boot service
Boot daemon to serve webhook request in PUSH_ARTIFACT event

``` shell
$ ./acceld --config ./misc/config/config.yaml
```

### Test image conversion

1. Trigger image conversion

We can either push an image to Harbor:

``` shell
$ docker push <harbor-service-address>/library/nginx:latest
```

Or convert an existing image manually using the `accelctl` CLI tool:

``` shell
$ ./accelctl task create <harbor-service-address>/library/nginx:latest
$ ./accelctl task list
```

2. Got converted image

If everything is ready, we can see the log output in acceleration service like this:

``` shell
INFO[2021-09-17T05:43:49.783769943Z] Version: ecbfefc312ea78d81eb895ef7768a60caa30a281.20210917.0543
INFO[2021-09-17T05:43:49.786146553Z] [API] HTTP server started on 0.0.0.0:2077
INFO[2021-09-17T05:44:01.82592358Z] received webhook request from 192.168.1.1:46664 module=api
INFO[2021-09-17T05:44:01.826490232Z] POST /api/v1/conversions 200 552.695µs 392>5bytes 192.168.1.1 module=api
INFO[2021-09-17T05:44:01.830893103Z] pulling image 192.168.1.1/library/nginx:latest module=converter
INFO[2021-09-17T05:44:01.916123236Z] pulled image 192.168.1.1/library/nginx:latest module=converter
INFO[2021-09-17T05:44:01.916175337Z] converting image 192.168.1.1/library/nginx:latest module=converter
INFO[2021-09-17T05:44:04.317992888Z] converted image 192.168.1.1/library/nginx:latest-nydus module=converter
```

After that, we will find converted artifact in Harbor interface with name `<harbor-service-address>/nginx:latest-nydus`.

### One-time mode

One-time mode allows to do a conversion without starting the `acceld` service, using `accelctl` like this:

```
$ accelctl convert --config ./misc/config/config.yaml 192.168.1.1/library/nginx:latest
## Documentation

INFO[2022-01-28T03:39:28.039029557Z] pulling image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:28.075375146Z] pulled image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:28.075530522Z] converting image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:29.561103924Z] converted image 192.168.1.1/library/nginx:latest-nydus module=converter
INFO[2022-01-28T03:39:29.561197593Z] pushing image 192.168.1.1/library/nginx:latest-nydus module=converter
INFO[2022-01-28T03:39:29.587585066Z] pushed image 192.168.1.1/library/nginx:latest-nydus module=converter
```
* [API](./docs/api.md)
* [Garbage Collection](./docs/garbage-collection.md)
* [QuickStart Tutorial](./docs/tutorial.md)

## Driver

Expand Down Expand Up @@ -145,8 +41,3 @@ type Driver interface {
### Testing

We can specify the driver name by modifying `converter.driver` in the configuration file, and modify the fields in `converter.config` to specify the driver-related configuration, see [example configuration file](./misc/config/config.estargz.yaml).

## Documentation

* [API](./docs/api.md)
* [Garbage Collection](./docs/garbage-collection.md)
119 changes: 119 additions & 0 deletions docs/tutorial.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# An Acceleration Service Tutorial for Beginners

## INTRODUCTION

### What is Acceleration Service?

Acceleration Service provides a general service to Harbor with the ability to
automatically convert user images to accelerated images([Nydus](https://github.com/dragonflyoss/image-service)
, [eStargz](https://github.com/containerd/stargz-snapshotter), etc).

Currently, Acceleration Service includes the following tools:

- An `accelctl` tool to tool to manage acceleration service.
- An `acceld` daemon to provide a general service to support image acceleration
based on kinds of accelerators like Nydus and eStargz etc. `Acceld` can work as
an HTTP server and expose some interfaces to accept conversion tasks.

### What will this tutorial teach me?

This tutorial aims to give you hands-on experience with converting your own
images in your harbor by `Acceleration Service` on host.

## GETTING STARTED

### Get Harbor

If you don't have a public harbor service, you can deploy a local harbor service.
Please see `Harbor` official [documentation](https://goharbor.io/docs/latest/install-config).

### Get binaries from release page

Get `accelctl` and `acceld` binaries from [acceleration-service release](https://github.com/goharbor/acceleration-service/releases/latest).

## Configuration

### Configure Habor

1. Login to the Harbor web interface.
2. Select one project and add a new Webhook configuration with the following fields:
* Notify Type: choose HTTP
* Event Type: Enable artifact pushed
* Endpoint URL: `<acceleration service address>`/api/v1/conversions
* Auth Header: `<configured in acceleration service>`
> Notice: The webhook can help to convert images automatically by acceleration service.
> If you only want to try the acceleration service, you can send HTTP request manually.
3. Create a system robot account with following fields:
* Expiration time: `<by your choice>`
* Reset permissions: select Push Artifact, Pull Artifact, Create Tag

When you Created 'robot$`<robot-name>`' successfully. Please copy the secret and
generate a base64 encoded auth string like this:
```bash
$ echo '<robot-name>:<robot-secret>' | base64
```
> Notice: The auth string will used in configuring acceleration service.

### Configure Acceleration Service

1. Copy the [template config file](https://github.com/goharbor/acceleration-service/tree/main/misc/config).
2. Modify the config file.
* Change `provider.source` with you own harbor service. You can change `hub.harbor.com`
to your own public harbor hostname. The `auth` has been generated by bash64. The `webhook.auth_header`
has configured in the harbor web interface.
* Change the settings of the accelerated image in `converter.driver`.
> Please follow the comments in the template config file.

## Convert Image with Acceleration Service

### Convert by acceld service
1. Boot acceld daemon in config file directory
```bash
$ ./acceld --config config.yaml
```
2. Trigger image conversion
* Push an image to trigger webhook.
```bash
$ docker push <harbor-service-address>/library/nginx:latest
```
* Convert manually by `accelctl` CLI tool.
> Please make sure the source oci images have been stored in your harbor.
```bash
$ ./accelctl task create <harbor-service-address>/library/nginx:latest
```
Or you can create a conversion task over the HTTP interface by `curl`. Please
refer to the [api document](./api.md).
```bash
$ curl --location 'http://<acceleration-service-address>/api/v1/conversions?sync=$snyc' \
--header 'Content-Type: application/json' \
--data '{
"type": "PUSH_ARTIFACT",
"event_data": {
"resources": [
{
"resource_url": "<harbor-service-address>/dfns/alpine:latest"
}
]
}
}
'
```

### One-time mode

One-time mode allows to do a conversion without starting the acceld service, using accelctl like this:
```
$ accelctl convert --config .config.yaml 192.168.1.1/library/nginx:latest

INFO[2022-01-28T03:39:28.039029557Z] pulling image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:28.075375146Z] pulled image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:28.075530522Z] converting image 192.168.1.1/library/nginx:latest module=converter
INFO[2022-01-28T03:39:29.561103924Z] converted image 192.168.1.1/library/nginx:latest-nydus module=converter
INFO[2022-01-28T03:39:29.561197593Z] pushing image 192.168.1.1/library/nginx:latest-nydus module=converter
INFO[2022-01-28T03:39:29.587585066Z] pushed image 192.168.1.1/library/nginx:latest-nydus module=converter
```
## Check Converted Image
You can see the converted image and source oci image in the some repo, they have different tag suffix.

0 comments on commit 2a0b71c

Please sign in to comment.