From cf23aee1831e464b2a445a1ffb302086f32dd6e5 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Sun, 13 Nov 2022 16:48:23 +0100 Subject: Add a "build" section, doc for SDK --- doc/book/build/_index.md | 54 +++++++++++++++++++++++++ doc/book/build/golang.md | 69 ++++++++++++++++++++++++++++++++ doc/book/build/javascript.md | 55 +++++++++++++++++++++++++ doc/book/build/others.md | 49 +++++++++++++++++++++++ doc/book/build/python.md | 95 ++++++++++++++++++++++++++++++++++++++++++++ doc/book/build/rust.md | 47 ++++++++++++++++++++++ 6 files changed, 369 insertions(+) create mode 100644 doc/book/build/_index.md create mode 100644 doc/book/build/golang.md create mode 100644 doc/book/build/javascript.md create mode 100644 doc/book/build/others.md create mode 100644 doc/book/build/python.md create mode 100644 doc/book/build/rust.md (limited to 'doc/book/build') diff --git a/doc/book/build/_index.md b/doc/book/build/_index.md new file mode 100644 index 00000000..9bb17086 --- /dev/null +++ b/doc/book/build/_index.md @@ -0,0 +1,54 @@ ++++ +title = "Build your own app" +weight = 4 +sort_by = "weight" +template = "documentation.html" ++++ + +Garage has many API that you can rely on to build complex applications. +In this section, we reference the existing SDKs and give some code examples. + + +## ⚠️ DISCLAIMER + +**K2V AND ADMIN SDK ARE TECHNICAL PREVIEWS**. The following limitations apply: + - The API is not complete, some actions are possible only through the `garage` binary + - The underlying admin API is not yet stable nor complete, it can breaks at any time + - The generator configuration is currently tweaked, the library might break at any time due to a generator change + - Because the API and the library are not stable, none of them are published in a package manager (npm, pypi, etc.) + - This code has not been extensively tested, some things might not work (please report!) + +To have the best experience possible, please consider: + - Make sure that the version of the library you are using is pinned (`go.sum`, `package-lock.json`, `requirements.txt`). + - Before upgrading your Garage cluster, make sure that you can find a version of this SDK that works with your targeted version and that you are able to update your own code to work with this new version of the library. + - Join our Matrix channel at `#garage:deuxfleurs.fr`, say that you are interested by this SDK, and report any friction. + - If stability is critical, mirror this repository on your own infrastructure, regenerate the SDKs and upgrade them at your own pace. + + +## About the APIs + +Code can interact with Garage through 3 different APIs: S3, K2V, and Admin. +Each of them has a specific scope. + +### S3 + +De-facto standard, introduced by Amazon, designed to store blobs of data. + +### K2V + +A simple database API similar to RiakKV or DynamoDB. +Think a key value store with some additional operations. +Its design is inspired by Distributed Hash Tables (DHT). + +More information: + - [In the reference manual](@/documentation/reference-manual/k2v.md) + + +### Administration + +Garage operations can also be automated through a REST API. +We are currently building this SDK for [Python](@/documentation/build/python.md#admin-api), [Javascript](@/documentation/build/javascript.md#administration) and [Golang](@/documentation/build/golang.md#administration). + +More information: + - [In the reference manual](@/documentation/reference-manual/admin-api.md) + - [Full specifiction](https://garagehq.deuxfleurs.fr/api/garage-admin-v0.html) diff --git a/doc/book/build/golang.md b/doc/book/build/golang.md new file mode 100644 index 00000000..a508260e --- /dev/null +++ b/doc/book/build/golang.md @@ -0,0 +1,69 @@ ++++ +title = "Golang" +weight = 30 ++++ + +## S3 + +*Coming soon* + +Some refs: + - Minio minio-go-sdk + - [Reference](https://docs.min.io/docs/golang-client-api-reference.html) + + - Amazon aws-sdk-go-v2 + - [Installation](https://aws.github.io/aws-sdk-go-v2/docs/getting-started/) + - [Reference](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3) + - [Example](https://aws.github.io/aws-sdk-go-v2/docs/code-examples/s3/putobject/) + +## K2V + +*Coming soon* + +## Administration + +Install the SDK with: + +```bash +go get git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang +``` + +A short example: + +```go +package main + +import ( + "context" + "fmt" + "os" + garage "git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang" +) + +func main() { + // Set Host and other parameters + configuration := garage.NewConfiguration() + configuration.Host = "127.0.0.1:3903" + + + // We can now generate a client + client := garage.NewAPIClient(configuration) + + // Authentication is handled through the context pattern + ctx := context.WithValue(context.Background(), garage.ContextAccessToken, "s3cr3t") + + // Send a request + resp, r, err := client.NodesApi.GetNodes(ctx).Execute() + if err != nil { + fmt.Fprintf(os.Stderr, "Error when calling `NodesApi.GetNodes``: %v\n", err) + fmt.Fprintf(os.Stderr, "Full HTTP response: %v\n", r) + } + + // Process the response + fmt.Fprintf(os.Stdout, "Target hostname: %v\n", resp.KnownNodes[resp.Node].Hostname) +} +``` + +See also: + - [generated doc](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-golang) + - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/golang) diff --git a/doc/book/build/javascript.md b/doc/book/build/javascript.md new file mode 100644 index 00000000..ff009ffe --- /dev/null +++ b/doc/book/build/javascript.md @@ -0,0 +1,55 @@ ++++ +title = "Javascript" +weight = 10 ++++ + +## S3 + +*Coming soon*. + +Some refs: + - Minio SDK + - [Reference](https://docs.min.io/docs/javascript-client-api-reference.html) + + - Amazon aws-sdk-js + - [Installation](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-started.html) + - [Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/latest/AWS/S3.html) + - [Example](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/s3-example-creating-buckets.html) + +## K2V + +*Coming soon* + +## Administration + +Install the SDK with: + +```bash +npm install --save git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js.git +``` + +A short example: + +```javascript +const garage = require('garage_administration_api_v0garage_v0_8_0'); + +const api = new garage.ApiClient("http://127.0.0.1:3903/v0"); +api.authentications['bearerAuth'].accessToken = "s3cr3t"; + +const [node, layout, key, bucket] = [ + new garage.NodesApi(api), + new garage.LayoutApi(api), + new garage.KeyApi(api), + new garage.BucketApi(api), +]; + +node.getNodes().then((data) => { + console.log(`nodes: ${Object.values(data.knownNodes).map(n => n.hostname)}`) +}, (error) => { + console.error(error); +}); +``` + +See also: + - [sdk repository](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-js) + - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/javascript) diff --git a/doc/book/build/others.md b/doc/book/build/others.md new file mode 100644 index 00000000..341e82d5 --- /dev/null +++ b/doc/book/build/others.md @@ -0,0 +1,49 @@ ++++ +title = "Others" +weight = 99 ++++ + +## S3 + +If you are developping a new application, you may want to use Garage to store your user's media. + +The S3 API that Garage uses is a standard REST API, so as long as you can make HTTP requests, +you can query it. You can check the [S3 REST API Reference](https://docs.aws.amazon.com/AmazonS3/latest/API/API_Operations_Amazon_Simple_Storage_Service.html) from Amazon to learn more. + +Developping your own wrapper around the REST API is time consuming and complicated. +Instead, there are some libraries already avalaible. + +Some of them are maintained by Amazon, some by Minio, others by the community. + +### PHP + + - Amazon aws-sdk-php + - [Installation](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/getting-started_installation.html) + - [Reference](https://docs.aws.amazon.com/aws-sdk-php/v3/api/api-s3-2006-03-01.html) + - [Example](https://docs.aws.amazon.com/sdk-for-php/v3/developer-guide/s3-examples-creating-buckets.html) + +### Java + + - Minio SDK + - [Reference](https://docs.min.io/docs/java-client-api-reference.html) + + - Amazon aws-sdk-java + - [Installation](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/get-started.html) + - [Reference](https://sdk.amazonaws.com/java/api/latest/software/amazon/awssdk/services/s3/S3Client.html) + - [Example](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/examples-s3-objects.html) + +### .NET + + - Minio SDK + - [Reference](https://docs.min.io/docs/dotnet-client-api-reference.html) + + - Amazon aws-dotnet-sdk + +### C++ + + - Amazon aws-cpp-sdk + +### Haskell + + - Minio SDK + - [Reference](https://docs.min.io/docs/haskell-client-api-reference.html) diff --git a/doc/book/build/python.md b/doc/book/build/python.md new file mode 100644 index 00000000..19912e85 --- /dev/null +++ b/doc/book/build/python.md @@ -0,0 +1,95 @@ ++++ +title = "Python" +weight = 20 ++++ + +## S3 + +*Coming soon* + +Some refs: + - Minio SDK + - [Reference](https://docs.min.io/docs/python-client-api-reference.html) + + - Amazon boto3 + - [Installation](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/quickstart.html) + - [Reference](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3.html) + - [Example](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/s3-uploading-files.html) + +## K2V + +*Coming soon* + +## Admin API + +You need at least Python 3.6, pip, and setuptools. +Because the python package is in a subfolder, the command is a bit more complicated than usual: + +```bash +pip3 install --user 'git+https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python' +``` + +Now, let imagine you have a fresh Garage instance running on localhost, with the admin API configured on port 3903 with the bearer `s3cr3t`: + +```python +import garage_admin_sdk +from garage_admin_sdk.apis import * +from garage_admin_sdk.models import * + +configuration = garage_admin_sdk.Configuration( + host = "http://localhost:3903/v0", + access_token = "s3cr3t" +) + +# Init APIs +api = garage_admin_sdk.ApiClient(configuration) +nodes, layout, keys, buckets = NodesApi(api), LayoutApi(api), KeyApi(api), BucketApi(api) + +# Display some info on the node +status = nodes.get_nodes() +print(f"running garage {status.garage_version}, node_id {status.node}") + +# Change layout of this node +current = layout.get_layout() +layout.add_layout({ + status.node: NodeClusterInfo( + zone = "dc1", + capacity = 1, + tags = [ "dev" ], + ) +}) +layout.apply_layout(LayoutVersion( + version = current.version + 1 +)) + +# Create key, allow it to create buckets +kinfo = keys.add_key(AddKeyRequest(name="openapi")) + +allow_create = UpdateKeyRequestAllow(create_bucket=True) +keys.update_key(kinfo.access_key_id, UpdateKeyRequest(allow=allow_create)) + +# Create a bucket, allow key, set quotas +binfo = buckets.create_bucket(CreateBucketRequest(global_alias="documentation")) +binfo = buckets.allow_bucket_key(AllowBucketKeyRequest( + bucket_id=binfo.id, + access_key_id=kinfo.access_key_id, + permissions=AllowBucketKeyRequestPermissions(read=True, write=True, owner=True), +)) +binfo = buckets.update_bucket(binfo.id, UpdateBucketRequest( + quotas=UpdateBucketRequestQuotas(max_size=19029801,max_objects=1500))) + +# Display key +print(f""" +cluster ready +key id is {kinfo.access_key_id} +secret key is {kinfo.secret_access_key} +bucket {binfo.global_aliases[0]} contains {binfo.objects}/{binfo.quotas.max_objects} objects +""") +``` + +*This example is named `short.py` in the example folder. Other python examples are also available.* + +See also: + - [sdk repo](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-python) + - [examples](https://git.deuxfleurs.fr/garage-sdk/garage-admin-sdk-generator/src/branch/main/example/python) + diff --git a/doc/book/build/rust.md b/doc/book/build/rust.md new file mode 100644 index 00000000..7101ba6e --- /dev/null +++ b/doc/book/build/rust.md @@ -0,0 +1,47 @@ ++++ +title = "Rust" +weight = 40 ++++ + +## S3 + +*Coming soon* + +Some refs: + - Amazon aws-rust-sdk + - [Github](https://github.com/awslabs/aws-sdk-rust) + +## K2V + +*Coming soon* + +Some refs: https://git.deuxfleurs.fr/Deuxfleurs/garage/src/branch/main/src/k2v-client + +```bash +# all these values can be provided on the cli instead +export AWS_ACCESS_KEY_ID=GK123456 +export AWS_SECRET_ACCESS_KEY=0123..789 +export AWS_REGION=garage +export K2V_ENDPOINT=http://172.30.2.1:3903 +export K2V_BUCKET=my-bucket + +cargo run --features=cli -- read-range my-partition-key --all + +cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string1" +cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string2" +cargo run --features=cli -- insert my-partition-key my-sort-key2 --text "my string" + +cargo run --features=cli -- read-range my-partition-key --all + +causality=$(cargo run --features=cli -- read my-partition-key my-sort-key2 -b | head -n1) +cargo run --features=cli -- delete my-partition-key my-sort-key2 -c $causality + +causality=$(cargo run --features=cli -- read my-partition-key my-sort-key -b | head -n1) +cargo run --features=cli -- insert my-partition-key my-sort-key --text "my string3" -c $causality + +cargo run --features=cli -- read-range my-partition-key --all +``` + +## Admin API + +*Coming soon* -- cgit v1.2.3