Add new Stacks resources (#1226)

* feat: add StackStates resource

* feat: add StackDeployments resource

* feat: add StackDiagnostics resources

* chore: remove beta notice from stacks resources

* chore: update changelog

* tests: add stack state tests

* tests: add stack diagnostic tests

* tests: remove beta gate for stacks integration tests

* chore: update changelog

* chore: incorporate review feedback

* chore: incorporate review feedback

* chore: incorporate review feedback

* add Links field to StackState struct

* tests: all stacks tests passing

* put skipUnlessBeta calls back in place

Author: ctrombley

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 * Add `Sort` option to `Agents` and `AgentPools`, by @twitnithegirl [#1229](https://github.com/hashicorp/go-tfe/pull/1229)
 * Add serialization for `StacksEnabled` field, `CanEnableStacks` & `CanCreateProject` permissions on Organization Read by @a-anurag27 [#1230](https://github.com/hashicorp/go-tfe/pull/1230)
+* Adds new stacks resources `StackDeployments`, `StackDiagnostics`, and `StackStates`, by @ctrombley [#1226](https://github.com/hashicorp/go-tfe/pull/1226)
+* Adds new `Diagnostics` methods to `StackConfigurations`, and `StackDeploymentSteps`, by @ctrombley [#1226](https://github.com/hashicorp/go-tfe/pull/1226)
+* Adds new `Artifacts` method to `StackDeploymentSteps`, by @ctrombley [#1226](https://github.com/hashicorp/go-tfe/pull/1226)
+* Add serialization for `StacksEnabled` field, `CanEnableStacks` & `CanCreateProject` permissions on Organization Read by @a-anurag27 [#1230](https://github.com/hashicorp/go-tfe/pull/1230)
 
 # v1.94.0
 

errors.go

@@ -251,6 +251,8 @@ var (
 	ErrInvalidHYOKCustomerKeyVersion = errors.New("invalid value for HYOK Customer key version ID")
 
 	ErrInvalidHYOKEncryptedDataKey = errors.New("invalid value for HYOK encrypted data key ID")
+
+	ErrInvalidStackID = errors.New("invalid value for stack ID")
 )
 
 var (

request.go

@@ -144,3 +144,58 @@ func (r *ClientRequest) DoJSON(ctx context.Context, model any) error {
 
 	return json.NewDecoder(resp.Body).Decode(model)
 }
+
+// DoRaw exposes the underlying io.ReadCloser for the response body.
+// The caller is responsible for closing the ReadCloser and unmarshaling the
+// results.
+func (r *ClientRequest) DoRaw(ctx context.Context) (io.ReadCloser, error) {
+	// Wait will block until the limiter can obtain a new token
+	// or returns an error if the given context is canceled.
+	if r.limiter != nil {
+		if err := r.limiter.Wait(ctx); err != nil {
+			return nil, err
+		}
+	}
+
+	// Add the context to the request.
+	contextReq := r.retryableRequest.WithContext(ctx)
+
+	// If the caller provided a response header hook then we'll call it
+	// once we have a response.
+	respHeaderHook, err := contextResponseHeaderHook(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	// Execute the request and check the response.
+	resp, err := r.http.Do(contextReq)
+	if resp != nil {
+		// We call the callback whenever there's any sort of response,
+		// even if it's returned in conjunction with an error.
+		respHeaderHook(resp.StatusCode, resp.Header)
+	}
+	if err != nil {
+		// If we got an error, and the context has been canceled,
+		// the context's error is probably more useful.
+		select {
+		case <-ctx.Done():
+			return nil, ctx.Err()
+		default:
+			return nil, err
+		}
+	}
+
+	if resp.StatusCode < 200 || resp.StatusCode >= 400 {
+		// Close the body here since we won't be returning it to the caller.
+		resp.Body.Close()
+		return nil, fmt.Errorf("error HTTP response: %d", resp.StatusCode)
+	} else if resp.StatusCode == 304 {
+		// Got a "Not Modified" response, but we can't return a model because there is no response body.
+		// This is necessary to support the IPRanges endpoint, which has the peculiar behavior
+		// of not returning content but allowing a 304 response by optionally sending an
+		// If-Modified-Since header.
+		return nil, nil
+	}
+
+	return resp.Body, nil
+}

stack.go

@@ -11,8 +11,6 @@ import (
 )
 
 // Stacks describes all the stacks-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 Stacks interface {
 	// List returns a list of stacks, optionally filtered by project.
 	List(ctx context.Context, organization string, options *StackListOptions) (*StackList, error)
@@ -138,22 +136,15 @@ type StackConfiguration struct {
 	IngressAttributes *IngressAttributes `jsonapi:"relation,ingress-attributes"`
 }
 
-// StackState represents a stack state
-type StackState struct {
-	// Attributes
-	ID                    string `jsonapi:"primary,stack-states"`
-	Description           string `jsonapi:"attr,description"`
-	Generation            int    `jsonapi:"attr,generation"`
-	Status                string `jsonapi:"attr,status"`
-	Deployment            string `jsonapi:"attr,deployment"`
-	Components            string `jsonapi:"attr,components"`
-	IsCurrent             bool   `jsonapi:"attr,is-current"`
-	ResourceInstanceCount int    `jsonapi:"attr,resource-instance-count"`
+// StackIncludeOpt represents the include options for a stack.
+type StackIncludeOpt string
 
-	// Relationships
-	Stack              *Stack              `jsonapi:"relation,stack"`
-	StackDeploymentRun *StackDeploymentRun `jsonapi:"relation,stack-deployment-run"`
-}
+const (
+	StackIncludeOrganization             StackIncludeOpt = "organization"
+	StackIncludeProject                  StackIncludeOpt = "project"
+	StackIncludeLatestStackConfiguration StackIncludeOpt = "latest_stack_configuration"
+	StackIncludeStackDiagnostics         StackIncludeOpt = "latest_stack_configuration.stack_diagnostics"
+)
 
 // StackListOptions represents the options for listing stacks.
 type StackListOptions struct {

stack_configuration.go

@@ -14,8 +14,6 @@ import (
 
 // 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 {
 	// CreateAndUpload packages and uploads the specified Terraform Stacks
 	// configuration files in association with a Stack.
@@ -28,7 +26,7 @@ type StackConfigurations interface {
 	Read(ctx context.Context, id string) (*StackConfiguration, error)
 
 	// ListStackConfigurations returns a list of stack configurations for a stack.
-	List(ctx context.Context, stackID string, options *StackConfigurationListOptions) (*StackConfigurationList, error)
+	List(ctx context.Context, stackID string, opts *StackConfigurationListOptions) (*StackConfigurationList, error)
 
 	// JSONSchemas returns a byte slice of the JSON schema for the stack configuration.
 	JSONSchemas(ctx context.Context, stackConfigurationID string) ([]byte, error)
@@ -42,6 +40,9 @@ type StackConfigurations interface {
 	// stack configuration as it progresses, until that status is "<status>",
 	// "errored", "canceled".
 	AwaitStatus(ctx context.Context, stackConfigurationID string, status StackConfigurationStatus) <-chan WaitForStatusResult
+
+	// Diagnostics returns the diagnostics for this stack configuration.
+	Diagnostics(ctx context.Context, stackConfigurationID string) (*StackDiagnosticsList, error)
 }
 
 type StackConfigurationStatus string
@@ -254,3 +255,19 @@ func (s stackConfigurations) pollForUploadURL(ctx context.Context, stackConfigur
 func (s stackConfigurations) UploadTarGzip(ctx context.Context, uploadURL string, archive io.Reader) error {
 	return s.client.doForeignPUTRequest(ctx, uploadURL, archive)
 }
+
+// Diagnostics returns the diagnostics for this stack configuration.
+func (s stackConfigurations) Diagnostics(ctx context.Context, stackConfigurationID string) (*StackDiagnosticsList, error) {
+	req, err := s.client.NewRequest("GET", fmt.Sprintf("stack-configurations/%s/stack-diagnostics", url.PathEscape(stackConfigurationID)), nil)
+
+	if err != nil {
+		return nil, err
+	}
+
+	diagnostics := &StackDiagnosticsList{}
+	err = req.Do(ctx, diagnostics)
+	if err != nil {
+		return nil, err
+	}
+	return diagnostics, nil
+}

stack_configuration_integration_test.go

@@ -122,3 +122,66 @@ func TestStackConfigurationCreateUploadAndRead(t *testing.T) {
 		require.Fail(t, "timed out waiting for stack configuration to be processed")
 	}
 }
+
+func TestStackConfigurationDiagnostics(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{
+
+		Project: orgTest.DefaultProject,
+		Name:    "test-stack",
+
+		VCSRepo: &StackVCSRepoOptions{
+			Identifier:   "ctrombley/linked-stacks-demo-network",
+			OAuthTokenID: oauthClient.OAuthTokens[0].ID,
+			Branch:       "diagnostics", // This branch will produce diagnostics
+		},
+	})
+	require.NoError(t, err)
+	require.NotNil(t, stack)
+
+	stackUpdated, err := client.Stacks.FetchLatestFromVcs(ctx, stack.ID)
+	require.NoError(t, err)
+	require.NotNil(t, stackUpdated)
+
+	stackUpdated, err = client.Stacks.Read(ctx, stackUpdated.ID)
+	require.NoError(t, err)
+	require.NotNil(t, stackUpdated.LatestStackConfiguration)
+
+	pollStackConfigurationStatus(t, ctx, client, stackUpdated.LatestStackConfiguration.ID, "failed")
+
+	t.Run("Diagnostics with valid ID", func(t *testing.T) {
+		diags, err := client.StackConfigurations.Diagnostics(ctx, stackUpdated.LatestStackConfiguration.ID)
+		assert.NoError(t, err)
+		require.NotEmpty(t, diags.Items)
+
+		diag := diags.Items[0]
+
+		assert.NotEmpty(t, diag.ID)
+		assert.NotEmpty(t, diag.Severity)
+		assert.NotEmpty(t, diag.Summary)
+		assert.NotEmpty(t, diag.Detail)
+		assert.NotEmpty(t, diag.Diags)
+		assert.False(t, diag.Acknowledged)
+		assert.Nil(t, diag.AcknowledgedAt)
+		assert.NotZero(t, diag.CreatedAt)
+
+		assert.Nil(t, diag.StackDeploymentStep)
+		assert.NotNil(t, diag.StackConfiguration)
+		assert.Nil(t, diag.AcknowledgedBy)
+	})
+
+	t.Run("Diagnostics with invalid ID", func(t *testing.T) {
+		_, err := client.StackConfigurations.Diagnostics(ctx, "invalid-id")
+		require.Error(t, err)
+	})
+}

stack_deployment.go

@@ -0,0 +1,53 @@
+package tfe
+
+import (
+	"context"
+	"fmt"
+	"net/url"
+)
+
+type StackDeployments interface {
+	// List returns a list of stack deployments for a given stack.
+	List(ctx context.Context, stackID string, opts *StackDeploymentListOptions) (*StackDeploymentList, error)
+}
+
+type StackDeployment struct {
+	// Attributes
+	ID   string `jsonapi:"primary,stack-deployments"`
+	Name string `jsonapi:"attr,name"`
+
+	// Relationships
+	Stack               *Stack              `jsonapi:"relation,stack"`
+	LatestDeploymentRun *StackDeploymentRun `jsonapi:"relation,latest-deployment-run"`
+}
+
+type stackDeployments struct {
+	client *Client
+}
+
+type StackDeploymentListOptions struct {
+	ListOptions
+}
+
+type StackDeploymentList struct {
+	*Pagination
+	Items []*StackDeployment
+}
+
+func (s stackDeployments) List(ctx context.Context, stackID string, opts *StackDeploymentListOptions) (*StackDeploymentList, error) {
+	if !validStringID(&stackID) {
+		return nil, ErrInvalidStackID
+	}
+
+	req, err := s.client.NewRequest("GET", fmt.Sprintf("stacks/%s/stack-deployments", url.PathEscape(stackID)), opts)
+	if err != nil {
+		return nil, err
+	}
+
+	var deployments StackDeploymentList
+	if err := req.Do(ctx, &deployments); err != nil {
+		return nil, err
+	}
+
+	return &deployments, nil
+}

stack_deployment_groups_integration_test.go

@@ -13,6 +13,7 @@ import (
 
 func TestStackDeploymentGroupsList(t *testing.T) {
 	skipUnlessBeta(t)
+
 	client := testClient(t)
 	ctx := context.Background()
 
@@ -78,6 +79,7 @@ func TestStackDeploymentGroupsList(t *testing.T) {
 
 func TestStackDeploymentGroupsRead(t *testing.T) {
 	skipUnlessBeta(t)
+
 	client := testClient(t)
 	ctx := context.Background()
 
@@ -222,7 +224,7 @@ func TestStackDeploymentGroupsRerun(t *testing.T) {
 	err = client.StackDeploymentGroups.ApproveAllPlans(ctx, deploymentGroupID)
 	require.NoError(t, err)
 
-	pollStackDeploymentRunForDeployingStatus(t, ctx, client, deploymentRuns.Items[0].ID)
+	pollStackDeploymentRunStatus(t, ctx, client, deploymentRuns.Items[0].ID, "deploying")
 
 	deploymentRunIds := []string{deploymentRuns.Items[0].ID}
 	for _, dr := range deploymentRuns.Items {

stack_deployment_integration_test.go

@@ -0,0 +1,65 @@
+package tfe
+
+import (
+	"context"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestStackDeploymentsList(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: "aa-test-stack",
+		VCSRepo: &StackVCSRepoOptions{
+			Identifier:   "hashicorp-guides/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.FetchLatestFromVcs(ctx, stack.ID)
+	require.NoError(t, err)
+	require.NotNil(t, stackUpdated)
+
+	stackUpdated = pollStackDeploymentGroups(t, ctx, client, stackUpdated.ID)
+
+	t.Run("List with valid options", func(t *testing.T) {
+		opts := &StackDeploymentListOptions{
+			ListOptions: ListOptions{
+				PageNumber: 1,
+				PageSize:   1,
+			},
+		}
+		sdl, err := client.StackDeployments.List(ctx, stackUpdated.ID, opts)
+		require.NoError(t, err)
+		require.NotNil(t, sdl)
+		require.Len(t, sdl.Items, 1)
+	})
+
+	t.Run("List with invalid options", func(t *testing.T) {
+		opts := &StackDeploymentListOptions{
+			ListOptions: ListOptions{
+				PageNumber: -1,
+				PageSize:   -1,
+			},
+		}
+
+		_, err := client.StackDeployments.List(ctx, stackUpdated.ID, opts)
+		require.Error(t, err)
+	})
+}