-
Notifications
You must be signed in to change notification settings - Fork 27
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Change: - Move the quick start from README to `docs/tutorial`. Signed-off-by: Yadong Ding <ding_yadong@foxmail.com>
- Loading branch information
1 parent
a7aa579
commit 2a0b71c
Showing
2 changed files
with
123 additions
and
113 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |