-
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.
Merge pull request #99 from kim-tsao/doc_updates
Update Registry Library docs
- Loading branch information
Showing
2 changed files
with
92 additions
and
48 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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,56 +1,96 @@ | ||
| # Devfile registry library | ||
|
|
||
| ## Overview | ||
| Devfile registry library is used for interacting with devfile registry, consumers can use devfile registry library to list stacks and/or samples of devfile registry, download the stack devfile and the whole stack from devfile registry. | ||
| The Devfile registry library is used to interact with the devfile registry to perform the following actions: | ||
|
|
||
| * List the indices of stacks and/or samples from a single registry or across multiple registries | ||
| * Download a stack with specific media types or all supported media types | ||
| * Send telemetry to the Devfile Registry service | ||
| * Filter stacks based on architectures | ||
|
|
||
| ## What's included | ||
| `./library`: package `library` which contains devfile registry library constants, variables and functions, documentations can be found [here](https://pkg.go.dev/github.com/devfile/registry-support/registry-library/library) | ||
| `./library`: package `library` which contains devfile registry library constants, variables and functions. Documentation can be found [here](https://pkg.go.dev/github.com/devfile/registry-support/registry-library/library) | ||
|
|
||
| `./build.sh`: build script to build `registry` binary to interact with devfile registry | ||
| `./build.sh`: build script to build the `registry-library` binary to interact with devfile registry | ||
|
|
||
| `./registry`: `registry` binary to interact with devfile registry | ||
| `./registry-library`: `registry-library` binary to interact with devfile registry | ||
|
|
||
| ## How to use it | ||
| 1. Import devfile registry library | ||
| ```go | ||
| import ( | ||
| registryLibrary "github.com/devfile/registry-support/registry-library/library" | ||
| ) | ||
| ``` | ||
| 2. Invoke devfile registry library | ||
|
|
||
| a. Get the index of devfile registry for various devfile types | ||
| ```go | ||
| registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, StackDevfileType) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| 1. Import the devfile registry library and index schema | ||
| ```go | ||
| import ( | ||
| registryLibrary "github.com/devfile/registry-support/registry-library/library" | ||
| indexSchema "github.com/devfile/registry-support/index/generator/schema" | ||
| ) | ||
| ``` | ||
|
|
||
| ### List the indices of stacks and/or samples | ||
| 1. Get the index for stack devfile types from a single registry | ||
|
|
||
| ```go | ||
| registryURL := "https://registry.devfile.io" | ||
| options := registryLibrary.RegistryOptions{} //leave empty if telemetry and architecture types are not relevant | ||
| registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, indexSchema.StackDevfileType) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| ``` | ||
| b. Get the indices of multiple devfile registries for various devfile types | ||
| 2. Get the index for all devfile types from a single registry | ||
| ```go | ||
| registryList := GetMultipleRegistryIndices(registryURLs, options, StackDevfileType) | ||
| devfileTypes := []indexSchema.DevfileType{indexSchema.StackDevfileType, indexSchema.SampleDevfileType} | ||
| registryIndex, err := registryLibrary.GetRegistryIndex(registryURL, options, devfileTypes...) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| ``` | ||
| c. Download the stack devfile from devfile registry | ||
|
|
||
| 3. Get the indices for various devfile stacks from multiple devfile registries | ||
| ```go | ||
| err := registryLibrary.PullStackByMediaTypesFromRegistry(registry, stack, registryLibrary.DevfileMediaTypeList, destDir, options) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| registryList := GetMultipleRegistryIndices(registryURLs, options, indexSchema.StackDevfileType) | ||
| ``` | ||
| d. Download the whole stack from devfile registry | ||
| #### Download the stack | ||
| Supported devfile media types can be found in the latest version of [library.go](https://github.com/devfile/registry-support/blob/main/registry-library/library/library.go) | ||
| 1. Download a stack devfile with a given media type from the devfile registry | ||
| ```go | ||
| err := registryLibrary.PullStackFromRegistry(registry, stack, destDir, options) | ||
| stack := "java-springboot" | ||
| destDir := "." | ||
| err := registryLibrary.PullStackByMediaTypesFromRegistry(registryURL, stack, registryLibrary.DevfileMediaTypeList, destDir, options) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| return err | ||
| } | ||
| ``` | ||
| e. Specify Options | ||
| 2. Download a stack with all supported media types from the devfile registry | ||
| ```go | ||
| options := RegistryOptions{ | ||
| User: user, | ||
| SkipTLSVerify: skipTLSVerify, | ||
| Filter: RegistryFilter{ | ||
| err := registryLibrary.PullStackFromRegistry(registryURL, stack, destDir, options) | ||
| if err != nil { | ||
| return err | ||
| } | ||
| ``` | ||
|
|
||
| #### Specify Registry Options | ||
| 1. Test a pre-prod registry installed with self-signed certificates | ||
| ```go | ||
| options := registryLibrary.RegistryOptions{ | ||
| SkipTLSVerify: "true", | ||
| } | ||
| ``` | ||
| 2. Filter Devfiles based on a set of architectures found in [header.go](https://github.com/devfile/api/blob/main/pkg/devfile/header.go) | ||
| ```go | ||
| architectures := []string{"amd64", "arm64"} | ||
| options := registryLibrary.RegistryOptions{ | ||
| Filter: registryLibrary.RegistryFilter{ | ||
| Architectures: architectures, | ||
| }, | ||
| } | ||
| ``` | ||
| 3. Send Telemetry data to the Devfile Registry | ||
| ```go | ||
| options := registryLibrary.RegistryOptions{ | ||
| Telemetry: registryLibrary.TelemetryData{ | ||
| User: "user-name" //this can be a generated UUID | ||
| Locale: "en_US" // set the OS or browser locale | ||
| Client: "client-name" //the name of the client | ||
| } | ||
| } | ||
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