More Stacks, StackPlans support

CHANGELOG.md

@@ -1,5 +1,7 @@
 # UNRELEASED
 
+* Adds more BETA support for `Stacks` resources, which is EXPERIMENTAL, SUBJECT TO CHANGE, and may not be available to all users by @brandonc. [#934](https://github.com/hashicorp/go-tfe/pull/934)
+
 # v1.59.0
 
 ## Features

stack.go

@@ -28,6 +28,9 @@ type Stacks interface {
 
 	// Delete deletes a stack.
 	Delete(ctx context.Context, stackID string) error
+
+	// UpdateConfiguration updates the configuration of a stack, triggering stack preparation.
+	UpdateConfiguration(ctx context.Context, stackID string) (*Stack, error)
 }
 
 // stacks implements Stacks.
@@ -82,7 +85,60 @@ type Stack struct {
 	UpdatedAt       time.Time     `jsonapi:"attr,updated-at,iso8601"`
 
 	// Relationships
-	Project *Project `jsonapi:"relation,project"`
+	Project                  *Project            `jsonapi:"relation,project"`
+	LatestStackConfiguration *StackConfiguration `jsonapi:"relation,latest-stack-configuration"`
+}
+
+// StackConfigurationStatusTimestamps represents the timestamps for a stack configuration
+type StackConfigurationStatusTimestamps struct {
+	QueuedAt     *time.Time `jsonapi:"attr,queued-at,omitempty,rfc3339"`
+	CompletedAt  *time.Time `jsonapi:"attr,completed-at,omitempty,rfc3339"`
+	PreparingAt  *time.Time `jsonapi:"attr,preparing-at,omitempty,rfc3339"`
+	EnqueueingAt *time.Time `jsonapi:"attr,enqueueing-at,omitempty,rfc3339"`
+	CanceledAt   *time.Time `jsonapi:"attr,canceled-at,omitempty,rfc3339"`
+	ErroredAt    *time.Time `jsonapi:"attr,errored-at,omitempty,rfc3339"`
+}
+
+// StackComponent represents a stack component, specified by configuration
+type StackComponent struct {
+	Name       string `json:"name"`
+	Correlator string `json:"correlator"`
+	Expanded   bool   `json:"expanded"`
+}
+
+// StackConfiguration represents a stack configuration snapshot
+type StackConfiguration struct {
+	// Attributes
+	ID                   string                              `jsonapi:"primary,stack-configurations"`
+	Status               string                              `jsonapi:"attr,status"`
+	StatusTimestamps     *StackConfigurationStatusTimestamps `jsonapi:"attr,status-timestamps"`
+	SequenceNumber       int                                 `jsonapi:"attr,sequence-number"`
+	DeploymentNames      []string                            `jsonapi:"attr,deployment-names"`
+	ConvergedDeployments []string                            `jsonapi:"attr,converged-deployments"`
+	Components           []*StackComponent                   `jsonapi:"attr,components"`
+	ErrorMessage         *string                             `jsonapi:"attr,error-message"`
+	EventStreamURL       string                              `jsonapi:"attr,event-stream-url"`
+}
+
+// StackDeployment represents a stack deployment, specified by configuration
+type StackDeployment struct {
+	// Attributes
+	ID            string    `jsonapi:"primary,stack-deployments"`
+	Name          string    `jsonapi:"attr,name"`
+	Status        string    `jsonapi:"attr,status"`
+	DeployedAt    time.Time `jsonapi:"attr,deployed-at,iso8601"`
+	ErrorsCount   int       `jsonapi:"attr,errors-count"`
+	WarningsCount int       `jsonapi:"attr,warnings-count"`
+	PausedCount   int       `jsonapi:"attr,paused-count"`
+
+	// Relationships
+	CurrentStackState *StackState `jsonapi:"relation,current-stack-state"`
+}
+
+// StackState represents a stack state
+type StackState struct {
+	// Attributes
+	ID string `jsonapi:"primary,stack-states"`
 }
 
 // StackListOptions represents the options for listing stacks.
@@ -110,6 +166,23 @@ type StackUpdateOptions struct {
 	VCSRepo     *StackVCSRepo `jsonapi:"attr,vcs-repo,omitempty"`
 }
 
+// UpdateConfiguration updates the configuration of a stack, triggering stack operations
+func (s *stacks) UpdateConfiguration(ctx context.Context, stackID string) (*Stack, error) {
+	req, err := s.client.NewRequest("POST", fmt.Sprintf("stacks/%s/actions/update-configuration", url.PathEscape(stackID)), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	stack := &Stack{}
+	err = req.Do(ctx, stack)
+	if err != nil {
+		return nil, err
+	}
+
+	return stack, nil
+}
+
+// List returns a list of stacks, optionally filtered by additional paameters.
 func (s stacks) List(ctx context.Context, organization string, options *StackListOptions) (*StackList, error) {
 	if err := options.valid(); err != nil {
 		return nil, err
@@ -129,6 +202,7 @@ func (s stacks) List(ctx context.Context, organization string, options *StackLis
 	return sl, nil
 }
 
+// Read returns a stack by its ID.
 func (s stacks) Read(ctx context.Context, stackID string) (*Stack, error) {
 	req, err := s.client.NewRequest("GET", fmt.Sprintf("stacks/%s", url.PathEscape(stackID)), nil)
 	if err != nil {
@@ -144,6 +218,7 @@ func (s stacks) Read(ctx context.Context, stackID string) (*Stack, error) {
 	return stack, nil
 }
 
+// Create creates a new stack.
 func (s stacks) Create(ctx context.Context, options StackCreateOptions) (*Stack, error) {
 	if err := options.valid(); err != nil {
 		return nil, err
@@ -163,6 +238,7 @@ func (s stacks) Create(ctx context.Context, options StackCreateOptions) (*Stack,
 	return stack, nil
 }
 
+// Update updates a stack.
 func (s stacks) Update(ctx context.Context, stackID string, options StackUpdateOptions) (*Stack, error) {
 	req, err := s.client.NewRequest("PATCH", fmt.Sprintf("stacks/%s", url.PathEscape(stackID)), &options)
 	if err != nil {
@@ -178,6 +254,7 @@ func (s stacks) Update(ctx context.Context, stackID string, options StackUpdateO
 	return stack, nil
 }
 
+// Delete deletes a stack.
 func (s stacks) Delete(ctx context.Context, stackID string) error {
 	req, err := s.client.NewRequest("POST", fmt.Sprintf("stacks/%s/delete", url.PathEscape(stackID)), nil)
 	if err != nil {

stack_configuration.go

@@ -0,0 +1,37 @@
+package tfe
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+)
+
+// StackConfigurations describes all the stacks configurations-related methods that the
+// HCP Terraform API supports.
+// NOTE WELL: This is a beta feature and is subject to change until noted otherwise in the
+// release notes.
+type StackConfigurations interface {
+	// ReadConfiguration returns a stack configuration by its ID.
+	Read(ctx context.Context, id string) (*StackConfiguration, error)
+}
+
+type stackConfigurations struct {
+	client *Client
+}
+
+var _ StackConfigurations = &stackConfigurations{}
+
+func (s stackConfigurations) Read(ctx context.Context, id string) (*StackConfiguration, error) {
+	req, err := s.client.NewRequest("GET", fmt.Sprintf("stack-configurations/%s", url.PathEscape(id)), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	stackConfiguration := &StackConfiguration{}
+	err = req.Do(ctx, stackConfiguration)
+	if err != nil {
+		return nil, err
+	}
+
+	return stackConfiguration, nil
+}

stack_deployments.go

@@ -0,0 +1,35 @@
+package tfe
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+)
+
+// StackDeployments describes all the stacks deployments-related methods that the
+// HCP Terraform API supports.
+// NOTE WELL: This is a beta feature and is subject to change until noted otherwise in the
+// release notes.
+type StackDeployments interface {
+	// Read returns a stack deployment by its name.
+	Read(ctx context.Context, stackID, deployment string) (*StackDeployment, error)
+}
+
+type stackDeployments struct {
+	client *Client
+}
+
+func (s stackDeployments) Read(ctx context.Context, stackID, deploymentName string) (*StackDeployment, error) {
+	req, err := s.client.NewRequest("GET", fmt.Sprintf("stacks/%s/stack-deployments/%s", url.PathEscape(stackID), url.PathEscape(deploymentName)), nil)
+	if err != nil {
+		return nil, err
+	}
+
+	deployment := &StackDeployment{}
+	err = req.Do(ctx, deployment)
+	if err != nil {
+		return nil, err
+	}
+
+	return deployment, nil
+}

stack_integration_test.go

@@ -6,6 +6,7 @@ package tfe
 import (
 	"context"
 	"testing"
+	"time"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
@@ -166,10 +167,156 @@ func TestStackReadUpdateDelete(t *testing.T) {
 	require.NoError(t, err)
 	require.Equal(t, "updated description", stackUpdated.Description)
 
+	stackUpdatedConfig, err := client.Stacks.UpdateConfiguration(ctx, stack.ID)
+	require.NoError(t, err)
+	require.Equal(t, stack.Name, stackUpdatedConfig.Name)
+
 	err = client.Stacks.Delete(ctx, stack.ID)
 	require.NoError(t, err)
 
 	stackReadAfterDelete, err := client.Stacks.Read(ctx, stack.ID)
 	require.ErrorIs(t, err, ErrResourceNotFound)
 	require.Nil(t, stackReadAfterDelete)
 }
+
+func pollStackDeployments(t *testing.T, ctx context.Context, client *Client, stackID string) (stack *Stack) {
+	t.Helper()
+
+	// pollStackDeployments will poll the given stack until it has deployments or the deadline is reached.
+	ctx, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))
+	defer cancel()
+
+	deadline, _ := ctx.Deadline()
+	t.Logf("Polling stack %q for deployments with deadline of %s", stackID, deadline)
+
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	for finished := false; !finished; {
+		t.Log("...")
+		select {
+		case <-ctx.Done():
+			t.Fatalf("Stack %q had no deployments at deadline", stackID)
+		case <-ticker.C:
+			var err error
+			stack, err = client.Stacks.Read(ctx, stackID)
+			if err != nil {
+				t.Fatalf("Failed to read stack %q: %s", stackID, err)
+			}
+
+			t.Logf("Stack %q had %d deployments", stack.ID, len(stack.DeploymentNames))
+			if len(stack.DeploymentNames) > 0 {
+				finished = true
+			}
+		}
+	}
+
+	return
+}
+
+func pollStackDeploymentStatus(t *testing.T, ctx context.Context, client *Client, stackID, deploymentName, status string) {
+	// pollStackDeployments will poll the given stack until it has deployments or the deadline is reached.
+	ctx, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))
+	defer cancel()
+
+	deadline, _ := ctx.Deadline()
+	t.Logf("Polling stack %q for deployments with deadline of %s", stackID, deadline)
+
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	for finished := false; !finished; {
+		t.Log("...")
+		select {
+		case <-ctx.Done():
+			t.Fatalf("Stack deployment %s/%s did not have status %q at deadline", stackID, deploymentName, status)
+		case <-ticker.C:
+			var err error
+			deployment, err := client.StackDeployments.Read(ctx, stackID, deploymentName)
+			if err != nil {
+				t.Fatalf("Failed to read stack deployment %s/%s: %s", stackID, deploymentName, err)
+			}
+
+			t.Logf("Stack deployment %s/%s had status %q", stackID, deploymentName, deployment.Status)
+			if deployment.Status == status {
+				finished = true
+			}
+		}
+	}
+}
+
+func pollStackConfigurationStatus(t *testing.T, ctx context.Context, client *Client, stackConfigID, status string) (stackConfig *StackConfiguration) {
+	// pollStackDeployments will poll the given stack until it has deployments or the deadline is reached.
+	ctx, cancel := context.WithDeadline(ctx, time.Now().Add(5*time.Minute))
+	defer cancel()
+
+	deadline, _ := ctx.Deadline()
+	t.Logf("Polling stack configuration %q for status %q with deadline of %s", stackConfigID, status, deadline)
+
+	ticker := time.NewTicker(2 * time.Second)
+	defer ticker.Stop()
+
+	var err error
+	for finished := false; !finished; {
+		t.Log("...")
+		select {
+		case <-ctx.Done():
+			t.Fatalf("Stack configuration %q did not have status %q at deadline", stackConfigID, status)
+		case <-ticker.C:
+			stackConfig, err = client.StackConfigurations.Read(ctx, stackConfigID)
+			if err != nil {
+				t.Fatalf("Failed to read stack configuration %q: %s", stackConfigID, err)
+			}
+
+			t.Logf("Stack configuration %q had status %q", stackConfigID, stackConfig.Status)
+			if stackConfig.Status == status {
+				finished = true
+			}
+		}
+	}
+
+	return
+}
+
+func TestStackConverged(t *testing.T) {
+	skipUnlessBeta(t)
+
+	client := testClient(t)
+	ctx := context.Background()
+
+	orgTest, orgTestCleanup := createOrganization(t, client)
+	t.Cleanup(orgTestCleanup)
+
+	oauthClient, cleanup := createOAuthClient(t, client, orgTest, nil)
+	t.Cleanup(cleanup)
+
+	stack, err := client.Stacks.Create(ctx, StackCreateOptions{
+		Name: "test-stack",
+		VCSRepo: &StackVCSRepo{
+			Identifier:   "brandonc/pet-nulls-stack",
+			OAuthTokenID: oauthClient.OAuthTokens[0].ID,
+		},
+		Project: &Project{
+			ID: orgTest.DefaultProject.ID,
+		},
+	})
+
+	require.NoError(t, err)
+	require.NotNil(t, stack)
+
+	stackUpdated, err := client.Stacks.UpdateConfiguration(ctx, stack.ID)
+	require.NoError(t, err)
+	require.NotNil(t, stackUpdated)
+
+	deployments := []string{"production", "staging"}
+
+	stack = pollStackDeployments(t, ctx, client, stackUpdated.ID)
+	require.ElementsMatch(t, deployments, stack.DeploymentNames)
+	require.NotNil(t, stack.LatestStackConfiguration)
+
+	for _, deployment := range deployments {
+		pollStackDeploymentStatus(t, ctx, client, stack.ID, deployment, "paused")
+	}
+
+	pollStackConfigurationStatus(t, ctx, client, stack.LatestStackConfiguration.ID, "converged")
+}