---
title: Go
url: /docs/esc/languages-sdks/go/
---


Pulumi ESC provides a Go SDK for managing environments and reading their configuration and secrets from your own code.

> **Note:** Use the ESC SDK to retrieve environment values from your application workloads at runtime and to manage environments programmatically. If you want to consume an environment from within a Pulumi IaC program, use [config](/docs/esc/guides/pulumi-iac/) instead of the SDK.

Here are some of the scenarios the SDK can automate:

* List environments and read environment definitions
* Open environments to access config and resolve secrets
* Create, update, decrypt, and delete environment definitions
* Supports both structured types and yaml text
* List environment revisions and create new revision tags
* Check environment definitions for errors

## Runtime support

The SDK supports any [supported version](https://go.dev/doc/devel/release#policy) of Go. We recommend using a recent release for the best experience.

## Install the SDK package

Run `go get github.com/pulumi/esc-sdk/sdk` to install the SDK package.

## Initializing ESC SDK client

The easiest way to initialize an ESC SDK client and authorization context is to run:

```go
import (
	esc "github.com/pulumi/esc-sdk/sdk/go"
)

authCtx, escClient, err := esc.DefaultLogin()
```

This method reads the access token from the `PULUMI_ACCESS_TOKEN` environment variable and returns an error if it isn't set. It doesn't fall back to Pulumi CLI credentials. The backend URL comes from the `PULUMI_BACKEND_URL` environment variable, which defaults to `https://api.pulumi.com`.

If the default behavior does not work for you, you can always manually initialize the client configuration and pass it into the client constructor:

```go
import (
	esc "github.com/pulumi/esc-sdk/sdk/go"
)

configuration := esc.NewConfiguration()
escClient := esc.NewClient(configuration)
authCtx := esc.NewAuthContext(myAccessToken)
```

## Examples

All of these examples expect a `PULUMI_ACCESS_TOKEN` and `PULUMI_ORG` environment variable to be set.

### Manage environment example

This example creates a new environment, opens that environment to access a secret, and then lists the environments.

```go
package main

import (
	"log"
	"os"

	esc "github.com/pulumi/esc-sdk/sdk/go"
)

func main() {
	orgName := os.Getenv("PULUMI_ORG")
	authCtx, escClient, err := esc.DefaultLogin()

	projName := "examples"
	envName := "sdk-go-example"
	// Create Environment
	err = escClient.CreateEnvironment(authCtx, orgName, projName, envName)
	if err != nil {
		log.Fatalf("Failed to create environment: %v", err)
	}

	// Update Environment with Secrets
	updatePayload := &esc.EnvironmentDefinition{
		Values: &esc.EnvironmentDefinitionValues{
			AdditionalProperties: map[string]interface{}{
				"my_secret": map[string]string{
					"fn::secret": "shh! don't tell anyone",
				},
			},
		},
	}

	_, err = escClient.UpdateEnvironment(authCtx, orgName, projName, envName, updatePayload)
	if err != nil {
		log.Fatalf("Failed to update environment: %v", err)
	}

	// Open and View Secrets
	_, values, err := escClient.OpenAndReadEnvironment(authCtx, orgName, projName, envName)
	if err != nil {
		log.Fatalf("Failed to open environment: %v", err)
	}

	mySecret, ok := values["my_secret"]
	if !ok {
		log.Fatalf("Secret 'my_secret' not found in environment %s/%s", projName, envName)
	}

	log.Printf("my_secret: %v\n", mySecret)

	orgEnvs, err := escClient.ListEnvironments(authCtx, orgName, nil)
	if err != nil {
		log.Fatalf("Failed to list environments: %v", err)
	}

	for _, orgEnv := range orgEnvs.Environments {
		log.Printf("Environment: %v/%v\n", orgEnv.Project, orgEnv.Name)
	}

}

```

### Tag revision example

This example lists revisions for an environment, tags a revision, and lists revision tags. It uses the `examples/sdk-go-example` environment from the [manage environment example](#manage-environment-example), so run that example first. The environment needs at least two revisions; otherwise, the example exits without tagging anything.

```go
package main

import (
	"log"
	"os"

	esc "github.com/pulumi/esc-sdk/sdk/go"
)

func main() {
	orgName := os.Getenv("PULUMI_ORG")
	authCtx, escClient, err := esc.DefaultLogin()

	projName := "examples"
	envName := "sdk-go-example"
	revs, err := escClient.ListEnvironmentRevisions(authCtx, orgName, projName, envName)
	if err != nil {
		log.Fatalf("Failed to list environment revisions: %v", err)
	}

	if len(revs) < 2 {
		return
	}

	// get the second latest revision
	secondLatestRev := revs[1]
	err = escClient.CreateEnvironmentRevisionTag(authCtx, orgName, projName, envName, "stable", secondLatestRev.Number)
	if err != nil {
		log.Fatalf("Failed to tag environment revision: %v", err)
	}

	log.Printf("Tagged revision %d as 'stable'", secondLatestRev.Number)

	tags, err := escClient.ListEnvironmentRevisionTags(authCtx, orgName, projName, envName)
	if err != nil {
		log.Fatalf("Failed to list environment revision tags: %v", err)
	}

	for _, tag := range tags.Tags {
		log.Printf("Tag %s at revision %d", tag.Name, tag.Revision)
	}
}

```

## Documentation

* [API Reference Documentation](https://pkg.go.dev/github.com/pulumi/esc-sdk/sdk/go)
* [Source repository](https://github.com/pulumi/esc-sdk)