Sceptre - AWS Cloud Provisioning Tool

Common errors

• sceptre.exceptions.SceptreException: Failed to parse config file: <path_to_config_file>.yaml

  cause The Sceptre configuration YAML file has incorrect syntax or uses a deprecated format (e.g., v3 config with a v4 Sceptre installation).
  fix Validate your YAML syntax using an online linter or `yamllint`. If you recently upgraded Sceptre to v4+, consult the official migration guide for configuration format changes.

• AttributeError: 'Stack' object has no attribute 'stack_group_config'

  cause You are attempting to access an attribute or object model that existed in Sceptre v3 (or earlier) but was removed or renamed in v4. This often occurs in custom resolvers or hooks.
  fix Update your custom Sceptre components (resolvers, hooks) to align with the Sceptre v4 API. Refer to the v4 migration guide for changes to the internal object model and configuration structure.

• ERROR: Account ID '...' is not valid for Stack Group '<path>'

  cause The AWS Account ID specified in your Sceptre configuration (or derived from environment variables/credentials) does not match the expected `account_id` defined in the stack group's config.
  fix Verify that your `account_id` in the Sceptre config files (e.g., `config/dev/config.yaml`) is correct. Also, check the `AWS_ACCOUNT_ID` or `SCEPTRE_ACCOUNT_ID` environment variables and ensure your AWS credentials are for the intended account.

• botocore.exceptions.ClientError: An error occurred (UnauthorizedOperation) when calling the GetTemplateSummary operation: Access Denied

  cause The AWS IAM role or user configured for Sceptre lacks the necessary permissions to perform the required CloudFormation or AWS service operations.
  fix Review the IAM policies attached to the AWS role/user Sceptre is using. Ensure it has permissions for `cloudformation:*`, `s3:*` (for templates), and any other AWS services your CloudFormation templates interact with (e.g., `ec2:*`, `lambda:*`).

Warnings

• breaking Sceptre v4.0.0 introduced significant breaking changes to the configuration file format and internal API. The `stack_group` concept was removed, `stack_group_config` was renamed, and resolver syntax changed.
  Fix: Review the Sceptre v4 migration guide in the official documentation. Update all `config/*.yaml` files and any custom resolvers/hooks to the new format. For Python 3.9 users, upgrade to Python 3.10+ as v4.0.0 requires it.
• breaking Sceptre v4.0.0 dropped support for Python versions older than 3.10. Users on Python 3.9 or earlier must upgrade their Python environment.
  Fix: Upgrade your Python installation to version 3.10 or newer (e.g., 3.10, 3.11, 3.12).
• gotcha Sceptre is primarily a CLI tool. While `sceptre.cli.sceptre` allows programmatic invocation of CLI commands, direct interaction with internal Sceptre objects (e.g., `Stack`, `StackGroup` instances) can be less stable or documented for general programmatic control. The internal API might change more frequently than the CLI interface.
  Fix: For most use cases, stick to the `sceptre.cli.sceptre` entry point when integrating Sceptre into Python scripts. Only delve into internal object manipulation when developing custom resolvers, hooks, or core Sceptre extensions, and be prepared for potential API changes between minor versions.
• gotcha Sceptre has a specific precedence for configuration values: CLI arguments > environment variables (e.g., `SCEPTRE_ACCOUNT_ID`, `SCEPTRE_REGION`) > config file values > default values. Misunderstanding this hierarchy can lead to unintended deployments (e.g., deploying to the wrong AWS account or region).
  Fix: Always explicitly define critical parameters like `account_id` and `region` in your `config/*.yaml` files. If using environment variables, ensure they are correctly set and not accidentally overridden or overriding a desired config value. Prioritize CLI flags for one-off overrides.

Install

• pip install sceptre Install Sceptre

Imports

• sceptre

  from sceptre.cli import sceptre

  The primary programmatic entry point for Sceptre CLI commands.

Quickstart

This quickstart demonstrates how to programmatically invoke Sceptre commands using its Python API. It runs a simple version check that doesn't require an AWS environment or a Sceptre project structure. For full functionality like deploying stacks, you would need a properly configured Sceptre project (with `config/` and `templates/` directories) and AWS credentials.

import os
import sys
from io import StringIO
from unittest.mock import patch
from sceptre.cli import sceptre

# Sceptre is primarily a CLI tool that operates on a project structure.
# For full functionality (e.g., `launch`, `validate`), you need:
# 1. A Sceptre project directory (e.g., `./config`, `./templates`).
# 2. AWS credentials configured (e.g., via ~/.aws/credentials, environment variables).

# This example demonstrates how to call a simple Sceptre command programmatically
# that does not require a project setup or AWS credentials, making it runnable.

print("Attempting to get Sceptre version programmatically...")

# Mock sys.stdout to capture output without affecting the console directly
with patch('sys.stdout', new_callable=StringIO) as mock_stdout:
    try:
        # Call the Sceptre CLI programmatically to get its version
        # This command is safe and does not require AWS setup.
        sceptre(["--version"])
        output = mock_stdout.getvalue()
        print(f"Sceptre version output:\n{output.strip()}")

    except SystemExit as e:
        # Sceptre CLI often uses sys.exit(), which `sceptre.cli.sceptre` reflects.
        # A SystemExit with code 0 usually indicates success for '--version'.
        if e.code != 0:
            print(f"Error: Sceptre command exited with code {e.code}")
        else:
            print(f"Sceptre command finished (exit code {e.code}).")

print("\nTo run actual Sceptre deployment commands (e.g., 'launch'):")
print("  1. Ensure you have a Sceptre project structure (config/ and templates/ directories).")
print("  2. Configure your AWS credentials (e.g., environment variables or ~/.aws/credentials).")
print("  Example (if project set up): # sceptre([\"launch\", \"dev/my-stack\"])")