Getting Started Guide feedback

[roleyfoley]

This discussion is to capture feedback on the getting started guide ( https://docs.hamlet.io/getting-started/ )

We want to capture as much feedback as we can for this guide to improve the first 20 minutes of users experience with hamlet

[roleyfoley]

From @ken9ross

Getting Started/AWS Serverless/Deploy Container/Hello Status API

The deployment:Unit parameter
States: This is useful when you have related components that can all be deployed at the same time.
Question: Should this be "must be deployed at the same time"? Also does this mean that we need/intend there to be a deployment:Sequence parameter in the future to allow for sequencing within a deployment unit or is this the purpose of deployment:Priority?

Getting Started/AWS Serverless/Deploy Container/API Configuration

Step 3 should include a warning that performing a dryrun without a confirm will display and then execute

[breca]

Under https://docs.hamlet.io/getting-started/install#getting-everything-installed

RE: Points 1/3 under Ubuntu/Windows WSL2

Consider doubling down on being opinionated and just give the reader sudo commands that they can lazily copy/paste, all the cool kids are doing it

[breca]

Instruction accuracy/consistency

Some of this feels extra nit picky but 🤷

Under https://docs.hamlet.io/getting-started/install:
mkdir -p ~/hamlet - the -p is unnecessary

Similarly, under https://docs.hamlet.io/getting-started/create-cmdb, we ask the reader to execute

mkdir ~/hamlet_hello/mycmdb - which differs from the above instruction, and will fail without -p

I think we should align all of these instructions (particularly the directory structure and accounts sections) so that they're consistent, and ensure that the instructions under the install section can be followed and allow the reader to flow seamlessly from beginning right through to examples

Preferably via judicious use of copy/paste

[breca]

Jargon busting

I think it may be worth having a glossary and link to it when using Hamlet specific terms, or possibly have a 'concepts explored in this section' header/footer that the reader can refer to when we're introducing new Hamlet concepts

[breca]

So I did later discover that you do provide this somewhat in https://docs.hamlet.io/in-depth/foundations/terminology

But it's unfinished and I think, far too buried

Another idea would simply be linking to the glossary when those terms are first mentioned, although I think this would make for a very jarring read

[breca]

Baseline deployment produced some unexpected warnings

The output generated from $ hamlet --account breca deploy run-deployments -u baseline did not match the output in the documentation -

Nota bene CMDB was generated using an old version of Hamlet, so this could be a lie

$ hamlet --account breca deploy run-deployments -u baseline

[*] segment/baseline

(Info) Generating outputs:
[*] entrance: deployment | output: contract | subset: generationcontract
[*] entrance: deployment | output: script | subset: prologue

 Hamlet Engine Logs
--------------------

- warn - Link occurrence not deployed - management-baseline -> management-baseline-cmk
- warn - Link occurrence not deployed - management-baseline -> management-baseline-opsdata                                                                                                           
--------------------
[-] warn : 2
[-] Compact log output format used set GENERATION_LOG_FORMAT=full for the complete details                                                                                                           
[*] entrance: deployment | output: resource

 Hamlet Engine Logs
--------------------

- warn - Link occurrence not deployed - management-baseline -> management-baseline-cmk                                                                                                               - warn - Link occurrence not deployed - management-baseline -> management-baseline-oai                                                                                                               - warn - Link occurrence not deployed - management-baseline -> management-baseline-opsdata                                                                                                           
--------------------
[-] warn : 3
[-] Compact log output format used set GENERATION_LOG_FORMAT=full for the complete details                                                                                                           
[*] entrance: deployment | output: script | subset: epilogue

 Hamlet Engine Logs
--------------------

- warn - Link occurrence not deployed - management-baseline -> management-baseline-cmk                                                                                                               - warn - Link occurrence not deployed - management-baseline -> management-baseline-opsdata                                                                                                           
--------------------
[-] warn : 2
[-] Compact log output format used set GENERATION_LOG_FORMAT=full for the complete details

[roleyfoley]

That one has been fixed up in hamlet-io/engine#1794

It hasn't made it to the latest tagged release as of yet.

[breca]

Post baseline deployment drift

After the instruction to edit segment.json, the list of available deployments was different than documentation

$ hamlet --account breca  deploy list-deployments
| Deployment Group   | Deployment Unit   | Provider   | State       | District   |
|--------------------|-------------------|------------|-------------|------------|
| segment            | baseline          | aws        | deployed    | segment    |
| segment            | vpc               | aws        | notdeployed | segment    |
| segment            | igw               | aws        | deployed    | segment    |
| segment            | nat               | aws        | notdeployed | segment    |
| segment            | ssh               | aws        | notdeployed | segment    |
| segment            | vpcendpoint       | aws        | deployed    | segment    |                                                                                                                          

All of those components were subsequently deployed

By the end of https://docs.hamlet.io/getting-started/aws-serverless/deploy-baseline/environment-bootstrap#what-was-deployed I had the following:

$ hamlet --account breca component list-occurrences

| TierId   | ComponentId   | Name                                              | Type               |
|----------|---------------|---------------------------------------------------|--------------------|
| mgmt     | baseline      | management-baseline-baseline                      | baseline           |
| mgmt     | baseline      | management-baseline-opsdata-baselinedata          | baselinedata       |
| mgmt     | baseline      | management-baseline-appdata-baselinedata          | baselinedata       |
| mgmt     | baseline      | management-baseline-ssh-baselinekey               | baselinekey        |
| mgmt     | baseline      | management-baseline-cmk-baselinekey               | baselinekey        |
| mgmt     | baseline      | management-baseline-oai-baselinekey               | baselinekey        |
| mgmt     | ssh           | management-ssh-bastion                            | bastion            |
| mgmt     | vpc           | management-vpc-network                            | network            |
| mgmt     | vpc           | management-vpc-internal-networkroute              | networkroute       |
| mgmt     | vpc           | management-vpc-external-networkroute              | networkroute       |
| mgmt     | vpc           | management-vpc-open-networkacl                    | networkacl         |
| mgmt     | igw           | management-igw-gateway                            | gateway            |
| mgmt     | igw           | management-igw-default-gatewaydestination         | gatewaydestination |
| mgmt     | nat           | management-nat-gateway                            | gateway            |
| mgmt     | nat           | management-nat-default-gatewaydestination         | gatewaydestination |
| mgmt     | vpcendpoint   | management-vpcendpoint-gateway                    | gateway            |
| mgmt     | vpcendpoint   | management-vpcendpoint-default-gatewaydestination | gatewaydestination |

[roleyfoley]

So this one is a bit interesting, a deployment is a collection of components, and components can have subcomponents. So its expected to actually have 6 deployments creating a heap of components.

We need to document that relationship more.

[breca]

The cautionary advice To clean up what has been deployed through these guides, at any time run.. states to execute

hamlet deploy run-deployments -d account -d segment --no-refresh-outputs -m stop

As a newcomer this heavily implies that this command will return me to a blank slate which isn't the case if you progress past the Account Setup page.

Regardless of that, I also encountered the following problems executing the command:

• s3xregistry fails to delete as the bucket is not empty
• account-s3 fails to delete due to the above

[roleyfoley]

You caught me :) I was aware of that one but forgot about it during the writing of the guide.

I've created hamlet-io/engine#1948 to track adding support for clearing s3 buckets on delete.