action

Documentation

Overview

Example (Install)

Install the bundle and only record the success/failure of the operation.

package main

import (
	"fmt"
	"time"

	"github.com/cnabio/cnab-go/action"
	"github.com/cnabio/cnab-go/bundle"
	"github.com/cnabio/cnab-go/claim"
	"github.com/cnabio/cnab-go/driver"
	"github.com/cnabio/cnab-go/driver/lookup"
	"github.com/cnabio/cnab-go/valuesource"
)

func main() {
	// Use the debug driver to only print debug information about the bundle but not actually execute it
	// Use "docker" to execute it for real
	d, err := lookup.Lookup("debug")
	if err != nil {
		panic(err)
	}

	// Create the action that will execute the operation
	a := action.New(d)

	// Get the definition of the bundle, usually you get this by pulling
	// the bundle from an OCI registry using github.com/cnabio/cnab-to-oci
	b := bundle.Bundle{
		SchemaVersion: bundle.GetDefaultSchemaVersion(),
		Name:          "mybuns",
		Version:       "1.0.0",
		InvocationImages: []bundle.InvocationImage{
			{
				BaseImage: bundle.BaseImage{
					ImageType: driver.ImageTypeDocker,
					Image:     "example.com/myorg/myinstaller",
					Digest:    "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474",
				},
			},
		},
		Actions: map[string]bundle.Action{
			"logs": {Modifies: false, Stateless: false},
		},
	}

	// Pass an empty set of parameters
	var parameters map[string]interface{}

	// Create a claim representing the inputs to the install operation
	c, err := claim.New("hello", claim.ActionInstall, b, parameters)
	if err != nil {
		panic(err)
	}

	// Set to consistent values so we can compare output reliably
	c.ID = "claim-id"
	c.Revision = "claim-rev"
	c.Created = time.Date(2020, time.April, 18, 1, 2, 3, 4, time.UTC)

	// Pass an empty set of credentials
	var creds valuesource.Set

	opResult, claimResult, err := a.Run(c, creds)
	if err != nil {
		// Something terrible has occurred and we could not even run the bundle
		panic(err)
	}

	// When there is no error, then both opResult and claimResult are populated
	if opResult.Error != nil {
		// The bundle ran but there was an error during execution
		fmt.Println("WARNING: bundle execution was unsuccessful")
	}
	// TODO: Persist claimResult
	fmt.Println("status:", claimResult.Status)

}

Output:

{
  "installation_name": "hello",
  "revision": "claim-rev",
  "action": "install",
  "parameters": null,
  "image": {
    "imageType": "docker",
    "image": "example.com/myorg/myinstaller",
    "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
  },
  "environment": {
    "CNAB_ACTION": "install",
    "CNAB_BUNDLE_NAME": "mybuns",
    "CNAB_BUNDLE_VERSION": "1.0.0",
    "CNAB_CLAIMS_VERSION": "1.0.0-DRAFT+b5ed2f3",
    "CNAB_INSTALLATION_NAME": "hello",
    "CNAB_REVISION": "claim-rev"
  },
  "files": {
    "/cnab/app/image-map.json": "{}",
    "/cnab/bundle.json": "{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}",
    "/cnab/claim.json": "{\"schemaVersion\":\"1.0.0-DRAFT+b5ed2f3\",\"id\":\"claim-id\",\"installation\":\"hello\",\"revision\":\"claim-rev\",\"created\":\"2020-04-18T01:02:03.000000004Z\",\"action\":\"install\",\"bundle\":{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}}"
  },
  "outputs": {},
  "Bundle": {
    "schemaVersion": "1.2.0",
    "name": "mybuns",
    "version": "1.0.0",
    "description": "",
    "invocationImages": [
      {
        "imageType": "docker",
        "image": "example.com/myorg/myinstaller",
        "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
      }
    ],
    "actions": {
      "logs": {}
    }
  }
}
status: succeeded

Example (Invoke)

Invoke the bundle and only record the success/failure of the operation.

// Use the debug driver to only print debug information about the bundle but not actually execute it
// Use "docker" to execute it for real
d, err := lookup.Lookup("debug")
if err != nil {
	panic(err)
}

// Pass an empty set of parameters
var parameters map[string]interface{}

// Load the previous claim for the installation
existingClaim := createInstallClaim()
if err != nil {
	panic(err)
}

// Create a claim for running the custom logs action based on the previous claim
c, err := existingClaim.NewClaim("logs", existingClaim.Bundle, parameters)
if err != nil {
	panic(err)
}

// Set to consistent values so we can compare output reliably
c.ID = "claim-id"
c.Revision = "claim-rev"
c.Created = time.Date(2020, time.April, 18, 1, 2, 3, 4, time.UTC)

// Create the action that will execute the operation
a := action.New(d)

// Determine if the action modifies the bundle's resources or if it doesn't
// For example like "logs", or "dry-run" would have modifies = false
modifies, err := c.IsModifyingAction()
if err != nil {
	panic(err)
}

// Pass an empty set of credentials
var creds valuesource.Set

opResult, claimResult, err := a.Run(c, creds)
if err != nil {
	// Something terrible has occurred and we could not even run the bundle
	panic(err)
}

// Only record the result of the operation when operation modifies resources
if modifies {
	// Only save the claim if it modified the bundle's resources
}

// When there is no error, then both opResult and claimResult are populated
if opResult.Error != nil {
	// The bundle ran but there was an error during execution
	fmt.Println("WARNING: bundle execution was unsuccessful")
}
// TODO: Persist claimResult
fmt.Println("status:", claimResult.Status)

Output:

{
  "installation_name": "hello",
  "revision": "claim-rev",
  "action": "logs",
  "parameters": null,
  "image": {
    "imageType": "docker",
    "image": "example.com/myorg/myinstaller",
    "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
  },
  "environment": {
    "CNAB_ACTION": "logs",
    "CNAB_BUNDLE_NAME": "mybuns",
    "CNAB_BUNDLE_VERSION": "1.0.0",
    "CNAB_CLAIMS_VERSION": "1.0.0-DRAFT+b5ed2f3",
    "CNAB_INSTALLATION_NAME": "hello",
    "CNAB_REVISION": "claim-rev"
  },
  "files": {
    "/cnab/app/image-map.json": "{}",
    "/cnab/bundle.json": "{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}",
    "/cnab/claim.json": "{\"schemaVersion\":\"1.0.0-DRAFT+b5ed2f3\",\"id\":\"claim-id\",\"installation\":\"hello\",\"revision\":\"claim-rev\",\"created\":\"2020-04-18T01:02:03.000000004Z\",\"action\":\"logs\",\"bundle\":{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}}"
  },
  "outputs": {},
  "Bundle": {
    "schemaVersion": "1.2.0",
    "name": "mybuns",
    "version": "1.0.0",
    "description": "",
    "invocationImages": [
      {
        "imageType": "docker",
        "image": "example.com/myorg/myinstaller",
        "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
      }
    ],
    "actions": {
      "logs": {}
    }
  }
}
status: succeeded

Example (RunningStatus)

Upgrade the bundle and record the operation as running immediately so that you can track how long the operation took.

package main

import (
	"fmt"
	"time"

	"github.com/cnabio/cnab-go/action"
	"github.com/cnabio/cnab-go/claim"
	"github.com/cnabio/cnab-go/driver/lookup"
	"github.com/cnabio/cnab-go/valuesource"
)

func saveResult(c claim.Claim, status string) {
	r, err := c.NewResult(status)
	if err != nil {
		panic(err)
	}

	fmt.Println("status:", r.Status)
	// TODO: persist the result
}

// Upgrade the bundle and record the operation as running immediately so that you can
// track how long the operation took.
func main() {
	// Use the debug driver to only print debug information about the bundle but not actually execute it
	// Use "docker" to execute it for real
	d, err := lookup.Lookup("debug")
	if err != nil {
		panic(err)
	}

	// Pass an empty set of parameters
	var parameters map[string]interface{}

	// Load the previous claim for the installation
	existingClaim := createInstallClaim()

	// Create a claim for the upgrade operation based on the previous claim
	c, err := existingClaim.NewClaim(claim.ActionUpgrade, existingClaim.Bundle, parameters)
	if err != nil {
		panic(err)
	}

	// Set to consistent values so we can compare output reliably
	c.ID = "claim-id"
	c.Revision = "claim-rev"
	c.Created = time.Date(2020, time.April, 18, 1, 2, 3, 4, time.UTC)

	// Create the action that will execute the operation
	a := action.New(d)

	// Pass an empty set of credentials
	var creds valuesource.Set

	// Save the upgrade claim in the Running Status
	saveResult(c, claim.StatusRunning)

	opResult, claimResult, err := a.Run(c, creds)
	if err != nil {
		// If the bundle isn't run due to an error preparing,
		// record a failure so we aren't left stuck in running
		saveResult(c, claim.StatusFailed)
		panic(err)
	}

	// When there is no error, then both opResult and claimResult are populated
	if opResult.Error != nil {
		// The bundle ran but there was an error during execution
		fmt.Println("WARNING: bundle execution was unsuccessful")
	}
	// TODO: Persist claimResult
	fmt.Println("status:", claimResult.Status)

}

Output:

status: running
{
  "installation_name": "hello",
  "revision": "claim-rev",
  "action": "upgrade",
  "parameters": null,
  "image": {
    "imageType": "docker",
    "image": "example.com/myorg/myinstaller",
    "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
  },
  "environment": {
    "CNAB_ACTION": "upgrade",
    "CNAB_BUNDLE_NAME": "mybuns",
    "CNAB_BUNDLE_VERSION": "1.0.0",
    "CNAB_CLAIMS_VERSION": "1.0.0-DRAFT+b5ed2f3",
    "CNAB_INSTALLATION_NAME": "hello",
    "CNAB_REVISION": "claim-rev"
  },
  "files": {
    "/cnab/app/image-map.json": "{}",
    "/cnab/bundle.json": "{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}",
    "/cnab/claim.json": "{\"schemaVersion\":\"1.0.0-DRAFT+b5ed2f3\",\"id\":\"claim-id\",\"installation\":\"hello\",\"revision\":\"claim-rev\",\"created\":\"2020-04-18T01:02:03.000000004Z\",\"action\":\"upgrade\",\"bundle\":{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}}"
  },
  "outputs": {},
  "Bundle": {
    "schemaVersion": "1.2.0",
    "name": "mybuns",
    "version": "1.0.0",
    "description": "",
    "invocationImages": [
      {
        "imageType": "docker",
        "image": "example.com/myorg/myinstaller",
        "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
      }
    ],
    "actions": {
      "logs": {}
    }
  }
}
status: succeeded

Example (Upgrade)

Install the bundle and only record the success/failure of the operation.

package main

import (
	"fmt"
	"time"

	"github.com/cnabio/cnab-go/action"
	"github.com/cnabio/cnab-go/bundle"
	"github.com/cnabio/cnab-go/claim"
	"github.com/cnabio/cnab-go/driver"
	"github.com/cnabio/cnab-go/driver/lookup"
	"github.com/cnabio/cnab-go/valuesource"
)

// Install the bundle and only record the success/failure of the operation.
func main() {
	// Use the debug driver to only print debug information about the bundle but not actually execute it
	// Use "docker" to execute it for real
	d, err := lookup.Lookup("debug")
	if err != nil {
		panic(err)
	}

	// Pass an empty set of parameters
	var parameters map[string]interface{}

	// Load the previous claim for the installation
	existingClaim := createInstallClaim()

	// Create a claim for the upgrade operation based on the previous claim
	c, err := existingClaim.NewClaim(claim.ActionUpgrade, existingClaim.Bundle, parameters)
	if err != nil {
		panic(err)
	}

	// Set to consistent values so we can compare output reliably
	c.ID = "claim-id"
	c.Revision = "claim-rev"
	c.Created = time.Date(2020, time.April, 18, 1, 2, 3, 4, time.UTC)

	// Create the action that will execute the operation
	a := action.New(d)

	// Pass an empty set of credentials
	var creds valuesource.Set

	opResult, claimResult, err := a.Run(c, creds)
	if err != nil {
		// Something terrible has occurred and we could not even run the bundle
		panic(err)
	}

	// When there is no error, then both opResult and claimResult are populated
	if opResult.Error != nil {
		// The bundle ran but there was an error during execution
		fmt.Println("WARNING: bundle execution was unsuccessful")
	}
	fmt.Println("status:", claimResult.Status)

}

func createInstallClaim() claim.Claim {
	b := bundle.Bundle{
		SchemaVersion: bundle.GetDefaultSchemaVersion(),
		Name:          "mybuns",
		Version:       "1.0.0",
		InvocationImages: []bundle.InvocationImage{
			{
				BaseImage: bundle.BaseImage{
					ImageType: driver.ImageTypeDocker,
					Image:     "example.com/myorg/myinstaller",
					Digest:    "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474",
				},
			},
		},
		Actions: map[string]bundle.Action{
			"logs": {Modifies: false, Stateless: false},
		},
	}

	// Pass an empty set of parameters
	var parameters map[string]interface{}

	c, err := claim.New("hello", claim.ActionInstall, b, parameters)
	if err != nil {
		panic(err)
	}
	return c
}

Output:

{
  "installation_name": "hello",
  "revision": "claim-rev",
  "action": "upgrade",
  "parameters": null,
  "image": {
    "imageType": "docker",
    "image": "example.com/myorg/myinstaller",
    "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
  },
  "environment": {
    "CNAB_ACTION": "upgrade",
    "CNAB_BUNDLE_NAME": "mybuns",
    "CNAB_BUNDLE_VERSION": "1.0.0",
    "CNAB_CLAIMS_VERSION": "1.0.0-DRAFT+b5ed2f3",
    "CNAB_INSTALLATION_NAME": "hello",
    "CNAB_REVISION": "claim-rev"
  },
  "files": {
    "/cnab/app/image-map.json": "{}",
    "/cnab/bundle.json": "{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}",
    "/cnab/claim.json": "{\"schemaVersion\":\"1.0.0-DRAFT+b5ed2f3\",\"id\":\"claim-id\",\"installation\":\"hello\",\"revision\":\"claim-rev\",\"created\":\"2020-04-18T01:02:03.000000004Z\",\"action\":\"upgrade\",\"bundle\":{\"schemaVersion\":\"1.2.0\",\"name\":\"mybuns\",\"version\":\"1.0.0\",\"description\":\"\",\"invocationImages\":[{\"imageType\":\"docker\",\"image\":\"example.com/myorg/myinstaller\",\"contentDigest\":\"sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474\"}],\"actions\":{\"logs\":{}}}}"
  },
  "outputs": {},
  "Bundle": {
    "schemaVersion": "1.2.0",
    "name": "mybuns",
    "version": "1.0.0",
    "description": "",
    "invocationImages": [
      {
        "imageType": "docker",
        "image": "example.com/myorg/myinstaller",
        "contentDigest": "sha256:7cc0618539fe11e801ce68911a0c9441a3dfaa9ba63057526c4016cf9db19474"
      }
    ],
    "actions": {
      "logs": {}
    }
  }
}
status: succeeded

Index

• Constants
• type Action
  • func New(d driver.Driver) Action
  • func (a Action) Run(c claim.Claim, creds valuesource.Set, opCfgs ...OperationConfigFunc) (driver.OperationResult, claim.Result, error)
• type OperationConfigFunc
• type OperationConfigs
  • func (cfgs OperationConfigs) ApplyConfig(op *driver.Operation) error

Examples

• Package (Install)
• Package (Invoke)
• Package (RunningStatus)
• Package (Upgrade)

Constants

const (
	ActionDryRun = "io.cnab.dry-run"
	ActionHelp   = "io.cnab.help"
	ActionLog    = "io.cnab.log"
	ActionStatus = "io.cnab.status"
)

Well known constants define the Well Known CNAB actions to be taken

Types

type Action

type Action struct {
	Driver driver.Driver

	// SaveLogs to the OperationResult.
	SaveLogs bool
}

Action executes a bundle operation and helps save the results.

func New

func New(d driver.Driver) Action

New creates an Action. - Driver to execute the operation with. - Claim Provider for persisting the claim data. If not set, calls to Save* will error.

func (Action) Run

func (a Action) Run(c claim.Claim, creds valuesource.Set, opCfgs ...OperationConfigFunc) (driver.OperationResult, claim.Result, error)

Run executes the action and records the status in a claim result. The caller is responsible for persisting the claim records and outputs using the SaveOperationResult function. An error is only returned when the operation could not be executed, otherwise any error is returned in the OperationResult.

type OperationConfigFunc

type OperationConfigFunc func(op *driver.Operation) error

OperationConfigFunc is a configuration function that can be applied to an operation.

type OperationConfigs

type OperationConfigs []OperationConfigFunc

OperationConfigs is a set of configuration functions that can be applied as a unit to an operation.

func (OperationConfigs) ApplyConfig

func (cfgs OperationConfigs) ApplyConfig(op *driver.Operation) error

ApplyConfig safely applies the configuration function to the operation, if defined, and stops immediately upon the first error.