From cbe30f32914efce0c516669c01c049d67b9a3e39 Mon Sep 17 00:00:00 2001 From: Vaughn Dice Date: Wed, 10 Jul 2019 12:58:55 -0600 Subject: [PATCH] feat(outputs): update schema, add documentation --- cmd/porter/bundle.go | 6 +----- docs/content/authoring-bundles.md | 35 +++++++++++++++++++++++++++---- docs/content/cli.md | 27 +++++++++++++++++++++++- pkg/porter/show.go | 31 +++++++++++++++++++++++++-- pkg/porter/templates/schema.json | 6 ++++++ pkg/porter/testdata/schema.json | 6 ++++++ 6 files changed, 99 insertions(+), 12 deletions(-) diff --git a/cmd/porter/bundle.go b/cmd/porter/bundle.go index c312476cc..68326ea25 100644 --- a/cmd/porter/bundle.go +++ b/cmd/porter/bundle.go @@ -1,7 +1,6 @@ package main import ( - "errors" "strings" "github.com/spf13/cobra" @@ -344,10 +343,7 @@ func buildBundleShowCommand(p *porter.Porter) *cobra.Command { Optional output formats include json and yaml. `, PreRunE: func(cmd *cobra.Command, args []string) error { - if len(args) == 0 { - return errors.New("a claim name must be provided") - } - return opts.Validate(args) + return opts.Validate(args, p.Context) }, RunE: func(cmd *cobra.Command, args []string) error { cp := cnab.NewDuffle(p.Config) diff --git a/docs/content/authoring-bundles.md b/docs/content/authoring-bundles.md index 57dc588a7..9ab1a33d5 100644 --- a/docs/content/authoring-bundles.md +++ b/docs/content/authoring-bundles.md @@ -8,6 +8,7 @@ Porter generates a bundle from its manifest, porter.yaml. The manifest is made u * [Bundle Metadata](#bundle-metadata) * [Mixins](#mixins) * [Parameters](#parameters) +* [Outputs](#outputs) * [Credentials](#credentials) * [Bundle Actions](#bundle-actions) * [Dependencies](#dependencies) @@ -87,11 +88,37 @@ parameters: * `path`: The path for the file. Required for file paths, there is no default. * `sensitive`: Optional. Designate this parameter's value as sensitive, for masking in console output. -### Parameter Schema +## Outputs -The [CNAB Spec for parameter definitions](https://github.com/deislabs/cnab-spec/blob/master/101-bundle-json.md#definitions) -has full support for [json schema](https://json-schema.org). We aren't quite there yet but -are working towards it. Here is what Porter supports for defining schema for parameters currently: +Outputs are part of the [CNAB Spec](https://github.com/deislabs/cnab-spec/blob/master/101-bundle-json.md#outputs) and +allow outputs generated during the course of executing a bundle to be accessed. These are global/bundle-wide outputs, +as opposed to step outputs described in [Parameters, Credentials and Outputs](/wiring/). However, as of writing, each +bundle output is only valid if it references a step output declared under one or more [bundle actions](#bundle-actions). + +```yaml +outputs: +- name: mysql_user + type: string + description: "MySQL user name" +- name: mysql_password + type: string + applyTo: + - "install" + - "upgrade" +``` + +* `name`: The name of the output. +* `type`: The data type of the output: string, integer, number, boolean. +* `applyTo`: (Optional) Restrict this output to a given list of actions. If empty or missing, applies to all actions. +* `description`: (Optional) A brief description of the given output. +* `sensitive`: (Optional) Designate an output as sensitive. Defaults to false. + +### Definition Schema for Parameters and Outputs + +The [CNAB Spec for definitions](https://github.com/deislabs/cnab-spec/blob/master/101-bundle-json.md#definitions) +applies to both parameters and outputs. It has full support for [json schema](https://json-schema.org). We aren't +quite there yet but are working towards it. Here is what Porter supports for defining schema for parameters and outputs +currently: * `default`: The default value for the parameter. When a default is not provided, the `required` is defaulted to true. * `required`: Specify if the parameter must be specified when the bundle is executed. diff --git a/docs/content/cli.md b/docs/content/cli.md index a4ce02784..04e8bf553 100644 --- a/docs/content/cli.md +++ b/docs/content/cli.md @@ -202,7 +202,7 @@ Global Flags: This command is available both as `porter bundle list` and `porter bundles list`. ```console - $ porter bundle list --help +$ porter bundle list --help List all bundles installed by Porter. A listing of bundles currently installed by Porter will be provided, along with @@ -226,6 +226,31 @@ Global Flags: --debug Enable debug logging ``` +### Bundle Show + +This command is available both as `porter bundle show` and `porter bundles show`. + +```console +$ porter bundle show --help +Displays info relating to a bundle claim, including status and a listing of outputs. + +Usage: + porter bundles show [CLAIM] [flags] + +Examples: + porter bundle show [CLAIM] + +Optional output formats include json and yaml. + + +Flags: + -h, --help help for show + -o, --output string Specify an output format. Allowed values: table, json, yaml (default "table") + +Global Flags: + --debug Enable debug logging +``` + ## Mixin Commands ### Mixins List diff --git a/pkg/porter/show.go b/pkg/porter/show.go index 301dc087b..56c5e2276 100644 --- a/pkg/porter/show.go +++ b/pkg/porter/show.go @@ -2,6 +2,7 @@ package porter import ( "fmt" + "os" "path/filepath" "time" @@ -10,6 +11,8 @@ import ( "github.com/pkg/errors" cnab "github.com/deislabs/porter/pkg/cnab/provider" + "github.com/deislabs/porter/pkg/config" + context "github.com/deislabs/porter/pkg/context" "github.com/deislabs/porter/pkg/printer" ) @@ -29,13 +32,32 @@ type ClaimListing struct { Outputs } -// Validate prepares for a show bundle action and validates the options. -func (so *ShowOptions) Validate(args []string) error { +// Validate prepares for a show bundle action and validates the args/options. +func (so *ShowOptions) Validate(args []string, cxt *context.Context) error { err := so.sharedOptions.validateClaimName(args) if err != nil { return err } + // If claim name not supplied, try to determine from manifest in current working directory + if so.sharedOptions.Name == "" { + pwd, err := os.Getwd() + if err != nil { + return errors.Wrap(err, "could not get current working directory") + } + + manifestExists, err := cxt.FileSystem.Exists(filepath.Join(pwd, config.Name)) + if err != nil { + return errors.Wrap(err, "could not check if porter manifest exists in current directory") + } + + if manifestExists { + so.sharedOptions.File = config.Name + } else { + return errors.New("claim name must be provided") + } + } + parsedFormat, err := printer.ParseFormat(so.RawFormat) if err != nil { return err @@ -48,7 +70,12 @@ func (so *ShowOptions) Validate(args []string) error { // ShowBundle shows a bundle, or more properly a bundle claim, along with any // associated outputs func (p *Porter) ShowBundle(opts ShowOptions, cp cnab.Provider) error { + err := p.applyDefaultOptions(&opts.sharedOptions) + if err != nil { + return err + } name := opts.sharedOptions.Name + claim, err := cp.FetchClaim(name) if err != nil { return err diff --git a/pkg/porter/templates/schema.json b/pkg/porter/templates/schema.json index 7567af5ad..db75a004e 100644 --- a/pkg/porter/templates/schema.json +++ b/pkg/porter/templates/schema.json @@ -38,6 +38,12 @@ "items": { "anyOf": [] } + }, + "outputs": { + "type": "array", + "items": { + "anyOf": [] + } } }, "additionalProperties": false, diff --git a/pkg/porter/testdata/schema.json b/pkg/porter/testdata/schema.json index faeb2f91b..8256d72d2 100644 --- a/pkg/porter/testdata/schema.json +++ b/pkg/porter/testdata/schema.json @@ -156,6 +156,12 @@ "name": { "type": "string" }, + "outputs": { + "items": { + "anyOf": [] + }, + "type": "array" + }, "uninstall": { "items": { "anyOf": [