From c0d2b104c1c80afced89b1eb5de1e24255c22066 Mon Sep 17 00:00:00 2001 From: Kim Tsao Date: Wed, 2 Feb 2022 13:39:10 -0500 Subject: [PATCH] Update Registry Library docs Signed-off-by: Kim Tsao --- registry-library/README.md | 108 +++++++++++++++++++--------- registry-library/library/library.go | 32 +++++---- 2 files changed, 92 insertions(+), 48 deletions(-) diff --git a/registry-library/README.md b/registry-library/README.md index a9a7192a..d04e436d 100644 --- a/registry-library/README.md +++ b/registry-library/README.md @@ -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 + } +} + + diff --git a/registry-library/library/library.go b/registry-library/library/library.go index faeb597d..aa7e319e 100644 --- a/registry-library/library/library.go +++ b/registry-library/library/library.go @@ -39,8 +39,7 @@ import ( ) const ( - // Devfile media types - DevfileConfigMediaType = "application/vnd.devfileio.devfile.config.v2+json" + // Supported Devfile media types DevfileMediaType = "application/vnd.devfileio.devfile.layer.v1" DevfileVSXMediaType = "application/vnd.devfileio.vsx.layer.v1.tar" DevfileSVGLogoMediaType = "image/svg+xml" @@ -63,28 +62,33 @@ type Registry struct { } //TelemetryData structure to pass in client telemetry information +// The User and Locale fields should be passed in by clients if telemetry opt-in is enabled +// the generic Client name will be passed in regardless of opt-in/out choice. The value +// will be assigned to the UserId field for opt-outs type TelemetryData struct { - // The User and Locale fields will be passed in by the clients if telemetry opt-in is enabled - User string + // User is a generated UUID or generic client name + User string + // Locale is the OS or browser locale Locale string - // the generic client name will be passed in regardless of opt-in/out choice. The value - // will be assigned to the UserId field for opt-outs + //Client is a generic name that describes the client Client string } type RegistryOptions struct { + // SkipTLSVerify is false by default which is the recommended setting for a devfile registry deployed in production. SkipTLSVerify should only be set to true + // if you are testing a devfile registry that is set up with self-signed certificates in a pre-production environment. SkipTLSVerify bool - Telemetry TelemetryData - Filter RegistryFilter + // Telemetry allows clients to send telemetry data to the community Devfile Registry + Telemetry TelemetryData + // Filter allows clients to specify which architectures they want to filter their devfiles on + Filter RegistryFilter } type RegistryFilter struct { Architectures []string } -// GetRegistryIndex returns the list of stacks and/or samples, more specifically -// it gets the stacks and/or samples content of the index of the specified registry -// for listing the stacks and/or samples +// GetRegistryIndex returns the list of index schema structured stacks and/or samples from a specified devfile registry. func GetRegistryIndex(registryURL string, options RegistryOptions, devfileTypes ...indexSchema.DevfileType) ([]indexSchema.Schema, error) { var registryIndex []indexSchema.Schema @@ -162,7 +166,7 @@ func GetRegistryIndex(registryURL string, options RegistryOptions, devfileTypes return registryIndex, nil } -// GetMultipleRegistryIndices returns returns the list of stacks and/or samples of multiple registries +// GetMultipleRegistryIndices returns the list of stacks and/or samples from multiple registries func GetMultipleRegistryIndices(registryURLs []string, options RegistryOptions, devfileTypes ...indexSchema.DevfileType) []Registry { registryList := make([]Registry, len(registryURLs)) registryContentsChannel := make(chan []indexSchema.Schema) @@ -210,7 +214,7 @@ func PrintRegistry(registryURLs string, devfileType string, options RegistryOpti return nil } -// PullStackByMediaTypesFromRegistry pulls stack from registry with allowed media types to the destination directory +// PullStackByMediaTypesFromRegistry pulls a specified stack with allowed media types from a given registry URL to the destination directory func PullStackByMediaTypesFromRegistry(registry string, stack string, allowedMediaTypes []string, destDir string, options RegistryOptions) error { // Get the registry index registryIndex, err := GetRegistryIndex(registry, options, indexSchema.StackDevfileType) @@ -278,7 +282,7 @@ func PullStackByMediaTypesFromRegistry(registry string, stack string, allowedMed return nil } -// PullStackFromRegistry pulls stack from registry with all stack resources (all media types) to the destination directory +// PullStackFromRegistry pulls a specified stack with all devfile supported media types from a registry URL to the destination directory func PullStackFromRegistry(registry string, stack string, destDir string, options RegistryOptions) error { return PullStackByMediaTypesFromRegistry(registry, stack, DevfileAllMediaTypesList, destDir, options) }