Update docs

ci/pipelines/vars.yml

@@ -1,6 +1,5 @@
 #@data/values
 ---
-
 stemcell_details:
   branch: ubuntu-jammy
   major_version: 1

ci/docs/fips.md → docs/fips.md

@@ -1,45 +1,53 @@
 # FIPS stemcells
 
 ## access to the fips stemcell buckets
+
 fips stemcells when published in the pipeline
 will be put in a private bucket called `bosh-core-stemcells-fips`
 
 if a working groups needs these fips stemcell the can retrieve them with the
-[bosh-io-stemcell](https://github.com/concourse/bosh-io-stemcell-resource) concourse resource =>1.2.1
+[bosh-io-stemcell](https://github.com/concourse/bosh-io-stemcell-resource) concourse resource => 1.2.1
 
 by setting
-```
+
+```yaml
 resources:
 - name: stemcell
   type: bosh-io-stemcell
   source:
     name: bosh-aws-xen-hvm-ubuntu-jammy-fips-go_agent
     auth:
-        access_key: hmac-accesskey
-        secret_key: hmac-secretkey
+        access_key: ((access_key-credhub_ref))
+        secret_key: ((secret_key-credhub_ref))
 ```
+
 for this you need a service account setup with hmac keys
 https://cloud.google.com/storage/docs/authentication/hmackeys
 
 ## setup access
-to setup access permissions for the `bosh-core-stemcells-fips` bucket
+
+setup access permissions for the `bosh-core-stemcells-fips` bucket
 
 ### working group actions
-a service accunt should be setup in the working group that want to access the fips stemcells.
+
+a service account should be setup in the working group that want to access the fips stemcells.
 this account should then be enabled with [hmac keys](https://cloud.google.com/storage/docs/authentication/hmackeys)
 
 #### bucket owner actions
+
 requirements:
 - [gcloud](https://cloud.google.com/sdk/docs/install)
 - [gsutil](https://cloud.google.com/storage/docs/gsutil_install)
 
-login to the cloud-foundry-310819 project ` gcloud auth login`
+Login to the `cloud-foundry-310819` GCP project `gcloud auth login` and setup
+access for cross-project buckets. In the example below replace PLACEHOLDER with
+the service account that is created in the previous steps. 
+Ex: `test-dev@myproject.iam.gserviceaccount.com`
 
-setup access for cross project cloud buckets. reference: https://cloud.google.com/dataprep/docs/concepts/gcs-buckets
-replace PLACEHOLDER with the service account that is created in the previous steps for example test-dev@myproject.iam.gserviceaccount.com
-```
-gsutil defacl ch -u PLACEHOLDER gs://bosh-core-stemcells-fips
+```shell
+gsutil defacl ch -u PLACEHOLDER:READER gs://bosh-core-stemcells-fips
 gsutil acl ch -u PLACEHOLDER:READER gs://bosh-core-stemcells-fips
 gsutil -m acl ch -r -u PLACEHOLDER:READER gs://bosh-core-stemcells-fips
 ```
 
+Reference: https://cloud.google.com/dataprep/docs/concepts/gcs-buckets

docs/new_stemcell_line.md

@@ -1,30 +1,40 @@
 # Creating a new stemcell line
 
-1. Create a new branch from the passing commit you want to release from. Use `{os_name}-{os_version}/{major}.x` format for branch name (e.g. `ubuntu-jammy/1.x`).
-
-    `git checkout -b <<BRANCH_NAME>> {commit}`
-
-1. Add, commit, and push the new branch.
-
+1. Create a new branch from the passing commit you want to release from. Use `ubuntu-${short_name}` format for branch name.
+
+   ```shell
+   export short_name="jammy"
+
+   git switch -c ubuntu-${short_name} {commit}
+   ```
+
+2. Update `ci/pipelines/vars.yml` with the appropriate values
+
+    ```yaml
+    #@data/values
+    stemcell_details:
+      branch: ubuntu-jammy
+    # ...
+    blobstore_types:
+      - dav
+    # ...
     ```
-    git push origin <<BRANCH_NAME>>
-    ```
-
-1. Switch back to master branch
 
-    ```
-    git checkout master
+3. Update `STEMCELL_LINE` in `ci/configure.sh`:
+
+    ```shell
+    STEMCELL_LINE="ubuntu-${short_name}"
     ```
 
-1. On master, update `ci/{os_name}-{os_version}/configure-aggregated-pipeline.sh` with the new branch details using the previous release branch as an example. Specifically, be sure to update the interpolated variables for the correct branch. For `initial_version`, use the same value of the stemcell produced by the commit in the `master` pipeline (e.g. `2.0.0`).
+4. Add, commit, and push the new branch.
 
+    ```shell
+    git push --set-upstream origin HEAD
     ```
-    ./ci/{os_name}-{os_version}/configure-aggregated-pipeline.sh
-    ```
-
-1. Once configured, the stemcell should automatically trigger and create the next minor version of the stemcell (e.g. `2.1.0`).
+5. Configure the new pipeline:
 
+    ```shell
+    ./ci/configure.sh
+    ```
 
-# References
-
-* [Stemcell Support Matrix](https://docs.google.com/spreadsheets/d/11LgvmuR-XxXpKB-UVi91FL0nkITGhoB-G1NHPwfnweo/edit) (internal only)
+6. Once configured, the stemcell pipeline should automatically trigger.

docs/publish.md

@@ -0,0 +1,53 @@
+# Publish a stemcell
+
+## Verify stemcells have built
+
+The following CI build groups process USN(s), and post a message to the 
+`#bosh-private` channel in the
+[Cloud Foundry slack](https://cloudfoundry.slack.com)
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-jammy-builder?group=automatic-triggers
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-noble-builder?group=automatic-triggers
+
+A USN triggers the stemcell build pipeline to pick up newer packages which
+address the USN(s). Before publishing a new stemcell verify the latest build of
+`aggregate-candidate-stemcells` job for the stemcell line in question:
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-jammy-builder/jobs/aggregate-candidate-stemcells
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-noble-builder/jobs/aggregate-candidate-stemcells
+
+Look for a successful build triggered by the USN(s).
+
+In the publisher pipelines:
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-jammy-publisher
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-noble-publisher
+
+verify that the lite stemcell builds for Google and AWS have been successfully
+triggered by the USN(s).
+
+## Publish stemcells
+
+In order to publish new stemcells, trigger a build of the
+`publish-ubuntu-${short_name}-1` job:
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-jammy-publisher/jobs/publish-ubuntu-jammy-1
+- https://bosh.ci.cloudfoundry.org/teams/stemcell/pipelines/ubuntu-noble-publisher/jobs/publish-ubuntu-noble-1
+
+This job will take around 1h to run. When this job is finished, new stemcell
+versions will be available on bosh.io and a GitHub draft release will have been
+created at
+- https://github.com/cloudfoundry/bosh-linux-stemcell-builder/releases.
+
+Check to see if the draft release has the correct USNs and CVEs, add any extra
+information (see below) to the release notes, and publish the GitHub release.
+
+Then [Finalize the draft release on GitHub](https://github.com/cloudfoundry/bosh-linux-stemcell-builder/releases)
+- Select the appropriate `Previous Tag` and click "Generate release notes" -
+  - Do NOT leave it set to `Auto` as that will result in incorrect release notes.
+- Scroll to the bottom; cut-and-paste the "What's Changed" section and paste it
+  at the top
+- Check the items for correctness; they may have already been published in a
+  previous release. Branch merges can confuse GitHub's auto-generated notes.
+- Reword the bullet items to convey what was fixed:
+
+| old (bad)                                    | new (good)                                                                                                            |
+|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|
+| 🐞 Fix “Cannot connect to the monit daemon.” | Fixed issue with BOSH service-broker tasks failing under heavy usage with error "Cannot connect to the monit daemon." |
+| Installing ethtool in Jammy by @<someone> in | Stemcells now include the networking utility, ethtool, useful for troubleshooting & resolving networking issues.      |