User's Guide

• Nucleator Overview — What is Nucleator and how do users interact with it?
• Nucleator Concepts and Domain Model — Key concepts used by Nucleator to define and manage the problem space
• How Nucleator Manages AWS Resources — Nucleator makes it easy for you to find and manage AWS Resources by consistently using thoughtful naming conventions and tags for everything that you ask it to create, and managing related AWS Resources together within CloudFormation stacks.
  • AWS Resource Creation and Naming Conventions — How Nucleator uses CloudFormation and adheres to design rules and conventions to consistently name AWS Resources across multiple AWS services.
  • Nucleator Resource Tagging — How Nucleator consistently tags AWS Resources to support robust business-level Account governance and cost accounting processes.
• Nucleator's Customizable Core — Nucleator works with git so you can get started with publicly available community Stacksets and you can customize and build new private Stacksets to meet your specific needs.
• How to Use Nucleator — A primer for getting started with Nucleator.
  • Installing and Configuring Nucleator — You can use Nucleator to create multiple Cages and Stacksets for multiple Customers, each of whom use multiple AWS Accounts. How to specify what you would like.
    • Nucleator Configuration Process Overview — Why Nucleator supports multiple AWS Accounts and Customers. What's contained in your siteconfig and an overview of the process used to configure Nucleator.
    • Installing Nucleator — How to get Nucleator
    • Creating your own Siteconfig Repository — How to create your own git repository to hold your desired Customer, Account and Cage definitions and information.
    • Choosing Nucleator Stacksets — How to initialize your configuration structure and tell Nucleator which public and private Stacksets you want to use.
    • Sign Up for New AWS Account using Nucleator Naming Conventions — How to sign up for a new AWS account for a Nucleator Customer using conventions and best practices that will make using Nucleator really easy.
    • Establish IAM Users and Minimal Configuration in New AWS Account — How to take the smallest possible set of manual actions on your AWS Account so that you can ask Nucleator to automate the rest.
    • Use the Nucleator Setup Wizard to Create an Initial Siteconfig — By interactively entering basic information and selecting all defaults, you can easily start using Nucleator with one Customer, one Account and one Cage.
    • Include Additional Customers, Accounts and Cages in your siteconfig — How to manually extend your siteconfig by telling Nucleator which AWS Accounts to use for which Customers, and which Cages and AWS Regions you want to become provisionable.
    • Provide SSL Certificates for Your Defined Customers and Cages — How to provide SSL certificates for use by the nucleator builder stackset or other stacksets that require them.
    • Update Chosen Stacksets — How to instruct Nucleator to update and locally install the Stacksets that you have specified to be part of your Nucleator installation.
  • Preparing New AWS Accounts for use with Nucleator — Nucleator makes automated actions available so you can set up new AWS Accounts with consist best practices and prepare for ongoing secure use of Nucleator.
    • Prepare AWS Account - Provisioning Your Account with required Nucleator IAM Roles — How to ask Nucleator to help you to install required IAM Roles using your IAM User Credentials, so that Nucleator can work securely on your behalf while provisioning and configuration Cages and Stacksets. How, when and why you use IAM User Credentials with Nucleator.
    • Prepare AWS Account - Use Nucleator to Automatically Create Prerequisite AWS Resources in Account — Ask Nucleator to prepare your AWS Account consistent with best practices and create resources needed to manage Cages and Stacksets.
    • Prepare AWS Account - Set Up DNS for Cages Defined Within Your Account — How to set up external DNS to route to the Nucleator Cages that you have defined
    • Prepare AWS Account - Set Up Billing and Reporting — How to enable detailed billing, select Nucleator Tags for detailed billing, and link your new Account to your Master Account for Consolidated Billing
  • Hardening your Nucleator Installation and Launching Nucleator's User Interface — Nucleator installs itself in a secure manner within the AWS Account that you specify within its own build Cage and builder Stackset, from which it provides a Jenkins-based User Interface that you can use as an alternative to the command line interface. Here's how to use the Nucleator command line interface to make it happen.
  • Using the Nucleator Command Line Interface — Nucleator provides a command line interface with commands and subcommands for common operations. Nucleator's User Interface uses the CLI under the covers. Sometimes you may want to use it too.
  • Using the Nucleator User Interface — Once your Builder Stackset is created, you can manage Cages and Stacksets through the Nucleator User Interface, which is based on a popular continuous integration application called Jenkins
    • Nucleator Operations — Some Nucleator User Interface projects operate on Nucleator as a whole
      • Checkout the Site Config — Update the Nucleator User Interface's concept of the site configuration
      • Nucleator Update — This project updates the Nucleator code on the nucleator machine
      • Provision Roles — If a new account is added, the roles need to be provisioned in that account.
      • Retrieving a Remote Ssh Config — Retrieve a remotely created ssh config file
      • Validate Rolespec — Validate that the Nucleator roles have been provisioned for an account
    • Using Cages within the Nucleator User Interface — How to provision, configure and delete cages using the Nucleator User Interface.
      • Provision and Configure a Cage — How to provision and configure Cages using the Nucleator User Interface.
      • Delete a Cage —  How to delete Cages using the Nucleator User Interface.
    • Using Stacksets within the Nucleator User Interface — How to create and use projects to interact with Nucleator Stacksets
      • Create a Stackset — Nucleator User Interface projects exist to create Stacksets of each known type
      • Create a Deployment Environment for an Application — The Nucleator User Interface enables you to create deployment environments and targets for your applications
      • Application Build and Deployment Projects — Nucleator's Builder Stackset also provides common, best-practice capabilities that support Continuous Integration and Delivery and that work in concert with other Nucleator Stacksets.
      • Delete a Stackset — When a Beanstalk Stackset is created in the Nucleator User Interface, one of the projects created is titled "Delete Beanstalk Container "
  • Using Nucleator Stacksets — You can use a variety of Nucleator Stacksets provided by 47Lining or by the community. You can use Stacksets out-of-the-box to get running quickly, or use them as a starting point for further customization.
    • ssh access and key management for Nucleator Cages and Stacksets — Nucleator makes it easy to access any of the instances within a Cage by generating an ssh config that enables access via the Cage's bastion.
    • Changing Default Instance Types within Nucleator Cages and Stacksets — How to change the EC2 instance types used when provisioning Nucleator Cages and Stacksets
    • Maintaining Network ACLs and Security Group Ingress/Egress Rules within Nucleator Cages and Stacksets — How to refine and extend the network ACL and security group ingress/egress rules used in Nucleator Cages and Stacksets
    • Nucleator Core - Cage — You can easily provision, configure and delete Nucleator Cages that implement high availability, scalability and security best practices.
    • Nucleator Core - Builder — Each Nucleator installation relies upon the Builder Stackset. It provides Nucleator's User Interface, a deployment of Nucleator within a Nucleator Cage, and an Artifactory instance for supporting continuous integration and deployment best practices.
    • Nucleator Core - Beanstalk — The Beanstalk stackset provides configurable Elastic Beanstalk Applications and Environments within Nucleator Cages.
    • Nucleator Core - Redshift — The Redshift Stackset provides configurable Redshift Clusters within Nucleator Cages.
    • Accessing a Private Redshift Cluster using an SSH Tunnel through your Cage's Bastion Server — How to securely access a private Redshift cluster from outside Nucleator
    • Using Nucleator for Continuous Integration and Delivery — Nucleator's Builder Stackset also provides common, best-practice capabilities that support Continuous Integration and Delivery and that work in concert with other Nucleator Stacksets.
  • Managing Nucleator Stacksets, Cages, and Manually Created AWS Resources — You can easily use AWS Resources that you create manually, or through other tools, together with Nucleator Cages and Stacksets. Doing so can create dependencies that you should understand.
    • Creating AWS Resources outside of Nucleator — In some environments it makes sense to use Nucleator to consistently set up parts of your environemnt and to create other AWS Resources manually or using other tools.
    • Deleting AWS Resources, Nucleator Cages and Stacksets — What to consider when deleting AWS Resources that are created and managed by Nucleator and CloudFormation, as well as those that are not
    • De-provisioning a Nucleator Account — How to revert the actions taken by account setup, so that you can start anew from a completely clean account
  • Creating and Maintaining Nucleator Stacksets — How to create your own Stacksets. You can create private Stacksets in a repository that only you or your customer can access, or in a public repository.
    • Creating Private or Public Stacksets — You create a Nucleator Stackset by cloning an existing Stackset, or Nucleator's Stackset Template, into your own public or private git repository.
    • What's in a Stackset? — The anatomy of a Nucleator Stackset. How and what to customize to meet your objectives.
    • Adding Stacksets to Your Nucleator Installation — How to tell Nucleator which versions of which Stacksets to use, and how to pull Stacksets from diverse public and private repositories.
    • Versioning Cages and Stacksets — How Nucleator and git work together to enable strong versioning of Nucleator Cages and Stacksets, as well as the Nucleator environments that are created from them.
• Architecture Diagrams
  • Account Setup
  • Nucleator Cage
  • Builder Stackset
  • Beanstalk Stackset
  • Redshift Stackset
  • Build Cage, Beanstalk Cage and Redshift Cage in One AWS Account
  • Build Cage, Beanstalk Cage and Redshift Cage in Three AWS Accounts
  • Build Cage and Beanstalk Cage in Two AWS Accounts
  • Build Cage and Redshift Cage in One AWS Account
  • Build Cage and Redshift Cage in Two AWS Accounts
  • Build Cage in One AWS Account
  • Cage with Builder Stackset
• Contributing to Nucleator — How to contribute to the Nucleator project
• Troubleshooting Tips — Guidance on troubleshooting common issues that may arise when using Nucleator
  • Using the CloudFormation Console with Nucleator — The CloudFormation Console provides a wealth of useful information about the status and outcomes of Nucleator commands that can be helpful in tracking progress as well as in troubleshooting.
  • Windows Tips — Nucleator runs on Linux, but there are several ways to use it from Windows
• Roadmap — Improvements to Nucleator after its initial open source release that may be valuable. 47Lining plans to continue to contribute, together with the Community.
• Glossary