Skip to content

Commit 0d578e7

Browse files
scottrigbyscottrigby
authored
Merge pull request #1543 from gjenkins8/sdkexamples
Helm SDK doc section and examples
2 parents f376b4c + 4009d9d commit 0d578e7

File tree

17 files changed

+1306
-66
lines changed

17 files changed

+1306
-66
lines changed

‎content/en/docs/community/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Community"
3-
weight: 7
3+
weight: 8
44
---
55

66
# Community Guides

‎content/en/docs/faq/_index.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
22
title: "Frequently Asked Questions"
3-
weight: 8
3+
weight: 9
44
aliases: [
55
"/docs/topics/faq/",
66
"/docs/faq/"

‎content/en/docs/glossary/_index.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
title: "Glossary"
2+
title: "Glossary"
33
description: "Terms used to describe components of Helm's architecture."
4-
weight: 9
4+
weight: 10
55
---
66

77
# Glossary

‎content/en/docs/sdk/_index.md

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Go SDK"
3+
weight: 7
4+
---

‎content/en/docs/sdk/examples.md

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
---
2+
title: "Examples"
3+
description: "Examples various features if the Helm SDK"
4+
weight: 2
5+
---
6+
7+
This document runs though a series of examples of using the Helm SDK.
8+
Intended to document various SDK functionalities.
9+
10+
The final example shows `main.go` driver ([link](#driver)). That runs the below actions and includes necessary helper functions.
11+
12+
The code for the examples lives in the [helm/helm-www/sdkexamples/](https://github.com/helm/helm-www/sdkexamples) directory.
13+
And is intended to be fully functional.
14+
15+
## Actions
16+
17+
18+
### Install Action
19+
20+
This example installs the given chart/release, for the given version and values:
21+
22+
{{< highlightexamplego file="sdkexamples/install.go" >}}
23+
24+
### Upgrade Action
25+
26+
This example upgrades the given release, with the given chart, version and values:
27+
28+
{{< highlightexamplego file="sdkexamples/upgrade.go" >}}
29+
30+
### Uninstall Action
31+
32+
This example uninstalls the given release
33+
34+
{{< highlightexamplego file="sdkexamples/uninstall.go" >}}
35+
36+
### List Action
37+
38+
This example lists all released charts (in the currently configured namespace)
39+
40+
{{< highlightexamplego file="sdkexamples/list.go" >}}
41+
42+
### Pull Action
43+
44+
This example pulls a chart from an OCI repository
45+
46+
{{< highlightexamplego file="sdkexamples/pull.go" >}}
47+
48+
## Driver
49+
50+
The driver here shows the necessary auxillary functions needed for the Helm SDK actions to function. And shows the above examples in action, to pull, install, update, and uninstall the 'podinfo' chart from an OCI repository.
51+
52+
{{< highlightexamplego file="sdkexamples/main.go" >}}

‎content/en/docs/sdk/gosdk.md

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: "Introduction"
3+
description: "Introduces the Helm Go SDK"
4+
aliases: ["/docs/gosdk"]
5+
weight: 1
6+
---
7+
Helm's Go SDK enables custom software to leverage Helm charts and Helm's functionality for managing Kubernetes software deployment
8+
(In fact, the Helm CLI is effectively just one such tool!)
9+
10+
Currently, the SDK has been functionally separated from the Helm CLI.
11+
And the SDK can (and is) used by standalone tooling.
12+
The Helm project has committed to API stability for the SDK.
13+
As a warning, the SDK has some rough edges remaining from the initial work to separate the CLI and the SDK. Which the Helm project aims to improve and over time.
14+
15+
Full API documentation can be found at [https://pkg.go.dev/helm.sh/helm/v3](https://pkg.go.dev/helm.sh/helm/v3).
16+
17+
A brief overview of some of the main types of packages and a simple example follows below.
18+
See the [Examples](./examples.md) section for more examples and a more full featured 'driver'.
19+
20+
## Main package overview
21+
22+
- [pkg/action](https://pkg.go.dev/helm.sh/helm/v3/pkg/action):
23+
Contains the main “client” for performing Helm actions.
24+
This is the same package that the CLI is using underneath the hood.
25+
If you just need to perform basic Helm commands from another Go program, this package is for you
26+
- [pkg/chart](https://pkg.go.dev/helm.sh/helm/v3/pkg/chart), [pkg/chartutil](https://pkg.go.dev/helm.sh/helm/v3/pkg/chartutil):
27+
Methods and helpers used for loading and manipulating charts
28+
- [pkg/chart](https://pkg.go.dev/helm.sh/helm/v3/pkg/cli) and its subpackages:
29+
Contains all the handlers for the standard Helm environment variables and its subpackages contain output and values file handling
30+
- [pkg/release](https://pkg.go.dev/helm.sh/helm/v3/pkg/release):
31+
Defines the `Release` object and statuses
32+
33+
There are many more packages besides these, so go check out the documentation for more information!
34+
35+
### Simple example
36+
This is a simple example of doing a `helm list` using the Go SDK.
37+
See the [Examples](./examples.md) section for more full featured examples.
38+
39+
```go
40+
package main
41+
42+
import (
43+
"log"
44+
"os"
45+
46+
"helm.sh/helm/v3/pkg/action"
47+
"helm.sh/helm/v3/pkg/cli"
48+
)
49+
50+
func main() {
51+
settings := cli.New()
52+
53+
actionConfig := new(action.Configuration)
54+
// You can pass an empty string instead of settings.Namespace() to list
55+
// all namespaces
56+
if err := actionConfig.Init(settings.RESTClientGetter(), settings.Namespace(), os.Getenv("HELM_DRIVER"), log.Printf); err != nil {
57+
log.Printf("%+v", err)
58+
os.Exit(1)
59+
}
60+
61+
client := action.NewList(actionConfig)
62+
// Only list deployed
63+
client.Deployed = true
64+
results, err := client.Run()
65+
if err != nil {
66+
log.Printf("%+v", err)
67+
os.Exit(1)
68+
}
69+
70+
for _, rel := range results {
71+
log.Printf("%+v", rel)
72+
}
73+
}
74+
75+
```
76+
77+
78+
## Compatibility
79+
80+
The Helm SDK explicitly follows the Helm backwards compatibility guarantees:
81+
82+
<https://github.com/helm/community/blob/main/hips/hip-0004.md>
83+
84+
That is, break changes will only be made over major versions.

‎content/en/docs/topics/advanced.md

Lines changed: 1 addition & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -83,68 +83,7 @@ For more information on using the Go SDK, See the [Go SDK section](#go-sdk)
8383
## Go SDK
8484
Helm 3 debuted a completely restructured Go SDK for a better experience when
8585
building software and tools that leverage Helm. Full documentation can be found
86-
at [https://pkg.go.dev/helm.sh/helm/v3](https://pkg.go.dev/helm.sh/helm/v3), but
87-
a brief overview of some of the most common packages and a simple example follow
88-
below.
89-
90-
### Package overview
91-
This is a list of the most commonly used packages with a simple explanation
92-
about each one:
93-
94-
- `pkg/action`: Contains the main “client” for performing Helm actions. This is
95-
the same package that the CLI is using underneath the hood. If you just need
96-
to perform basic Helm commands from another Go program, this package is for
97-
you
98-
- `pkg/{chart,chartutil}`: Methods and helpers used for loading and manipulating
99-
charts
100-
- `pkg/cli` and its subpackages: Contains all the handlers for the standard Helm
101-
environment variables and its subpackages contain output and values file
102-
handling
103-
- `pkg/release`: Defines the `Release` object and statuses
104-
105-
Obviously there are many more packages besides these, so go check out the
106-
documentation for more information!
107-
108-
### Simple example
109-
This is a simple example of doing a `helm list` using the Go SDK:
110-
111-
```go
112-
package main
113-
114-
import (
115-
"log"
116-
"os"
117-
118-
"helm.sh/helm/v3/pkg/action"
119-
"helm.sh/helm/v3/pkg/cli"
120-
)
121-
122-
func main() {
123-
settings := cli.New()
124-
125-
actionConfig := new(action.Configuration)
126-
// You can pass an empty string instead of settings.Namespace() to list
127-
// all namespaces
128-
if err := actionConfig.Init(settings.RESTClientGetter(), settings.Namespace(), os.Getenv("HELM_DRIVER"), log.Printf); err != nil {
129-
log.Printf("%+v", err)
130-
os.Exit(1)
131-
}
132-
133-
client := action.NewList(actionConfig)
134-
// Only list deployed
135-
client.Deployed = true
136-
results, err := client.Run()
137-
if err != nil {
138-
log.Printf("%+v", err)
139-
os.Exit(1)
140-
}
141-
142-
for _, rel := range results {
143-
log.Printf("%+v", rel)
144-
}
145-
}
146-
147-
```
86+
in the [Go SDK Section](../sdk/gosdk.md).
14887

14988
## Storage backends
15089

‎layouts/shortcodes/highlightexamplego.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{- transform.Highlight (os.ReadFile (.Get "file")) "go" }}

‎sdkexamples/README.md

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
# Helm Go SDK examples
2+
3+
This directory implements various Go SDK examples and a "driver".
4+
5+
These examples are fully working, and can be run by:
6+
7+
```
8+
# cd helm-www/sdkexamples
9+
$ go run ./...
10+
```

‎sdkexamples/go.mod

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
module github.com/helm/helm-www/sdkexamples
2+
3+
go 1.21.5
4+
5+
require (
6+
github.com/pkg/errors v0.9.1
7+
helm.sh/helm v2.17.0+incompatible
8+
helm.sh/helm/v3 v3.13.3
9+
)
10+
11+
require (
12+
github.com/AdaLogics/go-fuzz-headers v0.0.0-20230811130428-ced1acdcaa24 // indirect
13+
github.com/Azure/go-ansiterm v0.0.0-20210617225240-d185dfc1b5a1 // indirect
14+
github.com/BurntSushi/toml v1.3.2 // indirect
15+
github.com/MakeNowJust/heredoc v1.0.0 // indirect
16+
github.com/Masterminds/goutils v1.1.1 // indirect
17+
github.com/Masterminds/semver v1.5.0 // indirect
18+
github.com/Masterminds/semver/v3 v3.2.1 // indirect
19+
github.com/Masterminds/sprig/v3 v3.2.3 // indirect
20+
github.com/Masterminds/squirrel v1.5.4 // indirect
21+
github.com/Microsoft/hcsshim v0.11.0 // indirect
22+
github.com/asaskevich/govalidator v0.0.0-20200428143746-21a406dcc535 // indirect
23+
github.com/beorn7/perks v1.0.1 // indirect
24+
github.com/cespare/xxhash/v2 v2.2.0 // indirect
25+
github.com/chai2010/gettext-go v1.0.2 // indirect
26+
github.com/containerd/containerd v1.7.6 // indirect
27+
github.com/cyphar/filepath-securejoin v0.2.4 // indirect
28+
github.com/davecgh/go-spew v1.1.1 // indirect
29+
github.com/docker/cli v24.0.6+incompatible // indirect
30+
github.com/docker/distribution v2.8.2+incompatible // indirect
31+
github.com/docker/docker v24.0.7+incompatible // indirect
32+
github.com/docker/docker-credential-helpers v0.7.0 // indirect
33+
github.com/docker/go-connections v0.4.0 // indirect
34+
github.com/docker/go-metrics v0.0.1 // indirect
35+
github.com/docker/go-units v0.5.0 // indirect
36+
github.com/emicklei/go-restful/v3 v3.10.1 // indirect
37+
github.com/evanphx/json-patch v5.6.0+incompatible // indirect
38+
github.com/exponent-io/jsonpath v0.0.0-20151013193312-d6023ce2651d // indirect
39+
github.com/fatih/color v1.13.0 // indirect
40+
github.com/ghodss/yaml v1.0.0 // indirect
41+
github.com/go-errors/errors v1.4.2 // indirect
42+
github.com/go-gorp/gorp/v3 v3.1.0 // indirect
43+
github.com/go-logr/logr v1.2.4 // indirect
44+
github.com/go-logr/stdr v1.2.2 // indirect
45+
github.com/go-openapi/jsonpointer v0.19.6 // indirect
46+
github.com/go-openapi/jsonreference v0.20.2 // indirect
47+
github.com/go-openapi/swag v0.22.3 // indirect
48+
github.com/gobwas/glob v0.2.3 // indirect
49+
github.com/gogo/protobuf v1.3.2 // indirect
50+
github.com/golang/protobuf v1.5.3 // indirect
51+
github.com/google/btree v1.0.1 // indirect
52+
github.com/google/gnostic-models v0.6.8 // indirect
53+
github.com/google/go-cmp v0.5.9 // indirect
54+
github.com/google/gofuzz v1.2.0 // indirect
55+
github.com/google/shlex v0.0.0-20191202100458-e7afc7fbc510 // indirect
56+
github.com/google/uuid v1.3.0 // indirect
57+
github.com/gorilla/mux v1.8.0 // indirect
58+
github.com/gosuri/uitable v0.0.4 // indirect
59+
github.com/gregjones/httpcache v0.0.0-20180305231024-9cad4c3443a7 // indirect
60+
github.com/hashicorp/errwrap v1.1.0 // indirect
61+
github.com/hashicorp/go-multierror v1.1.1 // indirect
62+
github.com/huandu/xstrings v1.4.0 // indirect
63+
github.com/imdario/mergo v0.3.13 // indirect
64+
github.com/inconshreveable/mousetrap v1.1.0 // indirect
65+
github.com/jmoiron/sqlx v1.3.5 // indirect
66+
github.com/josharian/intern v1.0.0 // indirect
67+
github.com/json-iterator/go v1.1.12 // indirect
68+
github.com/klauspost/compress v1.16.0 // indirect
69+
github.com/lann/builder v0.0.0-20180802200727-47ae307949d0 // indirect
70+
github.com/lann/ps v0.0.0-20150810152359-62de8c46ede0 // indirect
71+
github.com/lib/pq v1.10.9 // indirect
72+
github.com/liggitt/tabwriter v0.0.0-20181228230101-89fcab3d43de // indirect
73+
github.com/mailru/easyjson v0.7.7 // indirect
74+
github.com/mattn/go-colorable v0.1.13 // indirect
75+
github.com/mattn/go-isatty v0.0.17 // indirect
76+
github.com/mattn/go-runewidth v0.0.9 // indirect
77+
github.com/matttproud/golang_protobuf_extensions v1.0.4 // indirect
78+
github.com/mitchellh/copystructure v1.2.0 // indirect
79+
github.com/mitchellh/go-wordwrap v1.0.1 // indirect
80+
github.com/mitchellh/reflectwalk v1.0.2 // indirect
81+
github.com/moby/locker v1.0.1 // indirect
82+
github.com/moby/spdystream v0.2.0 // indirect
83+
github.com/moby/term v0.5.0 // indirect
84+
github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
85+
github.com/modern-go/reflect2 v1.0.2 // indirect
86+
github.com/monochromegane/go-gitignore v0.0.0-20200626010858-205db1a8cc00 // indirect
87+
github.com/morikuni/aec v1.0.0 // indirect
88+
github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
89+
github.com/opencontainers/go-digest v1.0.0 // indirect
90+
github.com/opencontainers/image-spec v1.1.0-rc5 // indirect
91+
github.com/peterbourgon/diskv v2.0.1+incompatible // indirect
92+
github.com/prometheus/client_golang v1.16.0 // indirect
93+
github.com/prometheus/client_model v0.4.0 // indirect
94+
github.com/prometheus/common v0.44.0 // indirect
95+
github.com/prometheus/procfs v0.10.1 // indirect
96+
github.com/rubenv/sql-migrate v1.5.2 // indirect
97+
github.com/russross/blackfriday/v2 v2.1.0 // indirect
98+
github.com/shopspring/decimal v1.3.1 // indirect
99+
github.com/sirupsen/logrus v1.9.3 // indirect
100+
github.com/spf13/cast v1.5.0 // indirect
101+
github.com/spf13/cobra v1.7.0 // indirect
102+
github.com/spf13/pflag v1.0.5 // indirect
103+
github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb // indirect
104+
github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 // indirect
105+
github.com/xeipuuv/gojsonschema v1.2.0 // indirect
106+
github.com/xlab/treeprint v1.2.0 // indirect
107+
go.opentelemetry.io/otel v1.14.0 // indirect
108+
go.opentelemetry.io/otel/trace v1.14.0 // indirect
109+
go.starlark.net v0.0.0-20230525235612-a134d8f9ddca // indirect
110+
golang.org/x/crypto v0.14.0 // indirect
111+
golang.org/x/net v0.17.0 // indirect
112+
golang.org/x/oauth2 v0.8.0 // indirect
113+
golang.org/x/sync v0.3.0 // indirect
114+
golang.org/x/sys v0.13.0 // indirect
115+
golang.org/x/term v0.13.0 // indirect
116+
golang.org/x/text v0.13.0 // indirect
117+
golang.org/x/time v0.3.0 // indirect
118+
golang.org/x/tools v0.12.1-0.20230825192346-2191a27a6dc5 // indirect
119+
google.golang.org/appengine v1.6.7 // indirect
120+
google.golang.org/genproto/googleapis/rpc v0.0.0-20230525234030-28d5490b6b19 // indirect
121+
google.golang.org/grpc v1.56.3 // indirect
122+
google.golang.org/protobuf v1.31.0 // indirect
123+
gopkg.in/inf.v0 v0.9.1 // indirect
124+
gopkg.in/yaml.v2 v2.4.0 // indirect
125+
gopkg.in/yaml.v3 v3.0.1 // indirect
126+
k8s.io/api v0.28.4 // indirect
127+
k8s.io/apiextensions-apiserver v0.28.4 // indirect
128+
k8s.io/apimachinery v0.28.4 // indirect
129+
k8s.io/apiserver v0.28.4 // indirect
130+
k8s.io/cli-runtime v0.28.4 // indirect
131+
k8s.io/client-go v0.28.4 // indirect
132+
k8s.io/component-base v0.28.4 // indirect
133+
k8s.io/helm v2.17.0+incompatible // indirect
134+
k8s.io/klog/v2 v2.100.1 // indirect
135+
k8s.io/kube-openapi v0.0.0-20230717233707-2695361300d9 // indirect
136+
k8s.io/kubectl v0.28.4 // indirect
137+
k8s.io/utils v0.0.0-20230406110748-d93618cff8a2 // indirect
138+
oras.land/oras-go v1.2.4 // indirect
139+
sigs.k8s.io/json v0.0.0-20221116044647-bc3834ca7abd // indirect
140+
sigs.k8s.io/kustomize/api v0.13.5-0.20230601165947-6ce0bf390ce3 // indirect
141+
sigs.k8s.io/kustomize/kyaml v0.14.3-0.20230601165947-6ce0bf390ce3 // indirect
142+
sigs.k8s.io/structured-merge-diff/v4 v4.2.3 // indirect
143+
sigs.k8s.io/yaml v1.3.0 // indirect
144+
)

0 commit comments

Comments
 (0)