bedrock.yaml refactor & service create spec update

- Updated bedrock.yaml `services` to contain a list of services instead of a map
  indexed by path.
  - Auto-migration of bedrock.yaml is hooked into `read()` function of the
    `bedrockYaml.ts` file.
    - `read()` is now the only function used for loading the bedrock.yaml file;
      `Bedrock()` in `config.ts` is now noted as deprecated and now calls
      `read()` under the hood.
  - `path` property for a service now tracks the path to the service.
  - Documentation references all updated.
- `spk service create <service-name>` now follows the spec
  `spk service create <service-name> <service-path>`
  - Documentation references all updated.
  - Integration tests updated.

Author: evanlouie

docs/commands/data.json

@@ -334,7 +334,7 @@
     "alias": "r",
     "description": "Reconcile a HLD with the services tracked in bedrock.yaml.",
     "options": [],
-    "markdown": "## Description\n\nThe reconcile feature scaffolds a HLD with the services in the `bedrock.yaml`\nfile at the root level of the application repository. Recall that in a\nmono-repo, `spk service create` will add an entry into the `bedrock.yaml`\ncorresponding to all tracked services. When the service has been merged into\n`master` of the application repository, a pipeline (see `hld-lifecycle.yaml`,\ncreated by `spk project init`) runs `spk hld reconcile` to add any _new_\nservices tracked in `bedrock.yaml` to the HLD.\n\nThis command is _intended_ to be run in a pipeline (see the generated\n`hld-lifecycle.yaml` created from `spk project init`), but can be run by the\nuser in a CLI for verification.\n\nFor a `bedrock.yaml` file that contained within the\n`https://dev.azure.com/foo/bar/_git` repository, that has the following\nstructure:\n\n```yaml\nrings:\n  master:\n    isDefault: true\nservices:\n  ./services/fabrikam:\n    displayName: \"fabrikam\"\n    k8sBackendPort: 8001\n    k8sBackend: \"fabrikam-k8s-svc\"\n    pathPrefix: \"fabrikam-service\"\n    pathPrefixMajorVersion: \"v1\"\n    helm:\n      chart:\n        branch: master\n        git: \"https://dev.azure.com/foo/bar/_git\"\n        path: stable/fabrikam-application\n    middlewares:\n      - \"\"\nvariableGroups:\n  - fabrikam-vg\n```\n\nA HLD is produced that resembles the following:\n\n```\n├── component.yaml\n└── fabrikam\n    ├── access.yaml\n    ├── component.yaml\n    ├── config\n    │   └── common.yaml\n    └── fabrikam\n        ├── component.yaml\n        ├── config\n        │   └── common.yaml\n        └── master\n            ├── component.yaml\n            ├── config\n            │   └── common.yaml\n            └── static\n                ├── ingress-route.yaml\n                └── middlewares.yaml\n```\n\nWith the `ingress-route.yaml` representing a\n[Traefik2 Ingress Route](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-ingressroute)\nbacked by a Kubernetes Service, and the `middlewares.yaml` representing a\n[Traefik2 Middleware](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-middleware)\nthat strips path prefixes.\n\nFor the `bedrock.yaml` shown above, the `ingress-route.yaml` produced is:\n\n```yaml\napiVersion: traefik.containo.us/v1alpha1\nkind: IngressRoute\nmetadata:\n  name: fabrikam-master\nspec:\n  routes:\n    - kind: Rule\n      match: \"PathPrefix(`/v1/fabrikam-service`) && Headers(`Ring`, `master`)\"\n      middlewares:\n        - name: fabrikam-master\n      services:\n        - name: fabrikam-k8s-svc-master\n          port: 8001\n```\n\nAnd the `middlewares.yaml` produced is:\n\n```yaml\napiVersion: traefik.containo.us/v1alpha1\nkind: Middleware\nmetadata:\n  name: fabrikam-master\nspec:\n  stripPrefix:\n    forceSlash: false\n    prefixes:\n      - /v1/fabrikam-service\n```\n\nNote that there exists a third generated file, `access.yaml`. For the above\n`bedrock.yaml`, `access.yaml` contains a single line, which represents a\n[Fabrikate access.yaml definition](https://github.com/microsoft/fabrikate/blob/master/docs/auth.md#accessyaml),\nallowing Fabrikate to pull Helm Charts that are contained within the same\napplication repository:\n\n```yaml\n\"https://dev.azure.com/foo/bar/_git\": ACCESS_TOKEN_SECRET\n```\n\nWhen `fabrikate` is invoked in the HLD to Manifest pipeline, it will utilize the\n`ACCESS_TOKEN_SECRET` environment variable injected at pipeline run-time as a\nPersonal Access Token to pull any referenced helm charts from the application\nrepository.\n"
+    "markdown": "## Description\n\nThe reconcile feature scaffolds a HLD with the services in the `bedrock.yaml`\nfile at the root level of the application repository. Recall that in a\nmono-repo, `spk service create` will add an entry into the `bedrock.yaml`\ncorresponding to all tracked services. When the service has been merged into\n`master` of the application repository, a pipeline (see `hld-lifecycle.yaml`,\ncreated by `spk project init`) runs `spk hld reconcile` to add any _new_\nservices tracked in `bedrock.yaml` to the HLD.\n\nThis command is _intended_ to be run in a pipeline (see the generated\n`hld-lifecycle.yaml` created from `spk project init`), but can be run by the\nuser in a CLI for verification.\n\nFor a `bedrock.yaml` file that contained within the\n`https://dev.azure.com/foo/bar/_git` repository, that has the following\nstructure:\n\n```yaml\nrings:\n  master:\n    isDefault: true\nservices:\n  - path: ./services/fabrikam\n    displayName: \"fabrikam\"\n    k8sBackendPort: 8001\n    k8sBackend: \"fabrikam-k8s-svc\"\n    pathPrefix: \"fabrikam-service\"\n    pathPrefixMajorVersion: \"v1\"\n    helm:\n      chart:\n        branch: master\n        git: \"https://dev.azure.com/foo/bar/_git\"\n        path: stable/fabrikam-application\n    middlewares:\n      - \"\"\nvariableGroups:\n  - fabrikam-vg\n```\n\nA HLD is produced that resembles the following:\n\n```\n├── component.yaml\n└── fabrikam\n    ├── access.yaml\n    ├── component.yaml\n    ├── config\n    │   └── common.yaml\n    └── fabrikam\n        ├── component.yaml\n        ├── config\n        │   └── common.yaml\n        └── master\n            ├── component.yaml\n            ├── config\n            │   └── common.yaml\n            └── static\n                ├── ingress-route.yaml\n                └── middlewares.yaml\n```\n\nWith the `ingress-route.yaml` representing a\n[Traefik2 Ingress Route](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-ingressroute)\nbacked by a Kubernetes Service, and the `middlewares.yaml` representing a\n[Traefik2 Middleware](https://docs.traefik.io/routing/providers/kubernetes-crd/#kind-middleware)\nthat strips path prefixes.\n\nFor the `bedrock.yaml` shown above, the `ingress-route.yaml` produced is:\n\n```yaml\napiVersion: traefik.containo.us/v1alpha1\nkind: IngressRoute\nmetadata:\n  name: fabrikam-master\nspec:\n  routes:\n    - kind: Rule\n      match: \"PathPrefix(`/v1/fabrikam-service`) && Headers(`Ring`, `master`)\"\n      middlewares:\n        - name: fabrikam-master\n      services:\n        - name: fabrikam-k8s-svc-master\n          port: 8001\n```\n\nAnd the `middlewares.yaml` produced is:\n\n```yaml\napiVersion: traefik.containo.us/v1alpha1\nkind: Middleware\nmetadata:\n  name: fabrikam-master\nspec:\n  stripPrefix:\n    forceSlash: false\n    prefixes:\n      - /v1/fabrikam-service\n```\n\nNote that there exists a third generated file, `access.yaml`. For the above\n`bedrock.yaml`, `access.yaml` contains a single line, which represents a\n[Fabrikate access.yaml definition](https://github.com/microsoft/fabrikate/blob/master/docs/auth.md#accessyaml),\nallowing Fabrikate to pull Helm Charts that are contained within the same\napplication repository:\n\n```yaml\n\"https://dev.azure.com/foo/bar/_git\": ACCESS_TOKEN_SECRET\n```\n\nWhen `fabrikate` is invoked in the HLD to Manifest pipeline, it will utilize the\n`ACCESS_TOKEN_SECRET` environment variable injected at pipeline run-time as a\nPersonal Access Token to pull any referenced helm charts from the application\nrepository.\n"
   },
   "infra generate": {
     "command": "generate",
@@ -556,7 +556,7 @@
     "markdown": "## Description\n\nGenerate a PR in Azure DevOps against default ring branches\n"
   },
   "service create": {
-    "command": "create <service-name>",
+    "command": "create <service-name> <service-path>",
     "alias": "c",
     "description": "Add a new service into this initialized spk project repository",
     "options": [
@@ -595,11 +595,6 @@
         "description": "The directory containing the mono-repo packages.",
         "defaultValue": ""
       },
-      {
-        "arg": "-n, --display-name <display-name>",
-        "description": "Display name of the service.",
-        "defaultValue": ""
-      },
       {
         "arg": "-m, --maintainer-name <maintainer-name>",
         "description": "The name of the primary maintainer for this service.",
@@ -641,7 +636,7 @@
         "defaultValue": ""
       }
     ],
-    "markdown": "## Description\n\nAdd a new service into this initialized spk project repository.\n\n## Example\n\n```bash\nspk service create . \\\n  --display-name $app_name \\\n  --helm-config-path $path_to_chart_in_repo \\\n  --helm-config-git $helm_repo_url \\ # Needs to start with https and not contain user name\n  --helm-config-branch master \\\n  --helm-chart-access-token-variable $ENV_VAR_NAME\n```\n\n## Note\n\n- `--helm-chart-*` and `--helm-config-*` settings are mutually-exclusive. **You\n  may only use one.**\n  - If the git repository referenced in `--helm-config-git` is a private\n    repository, you can specify an environment variable in your\n    HLD-to-Materialized pipeline containing your a PAT to authenticate with via\n    the `--helm-chart-access-token-variable` option.\n- `--middlewares`, `--k8s-backend-port`, `--path-prefix`,\n  `--path-prefix-major-version`, and `--k8s-backend` are all used to configure\n  the generated Traefik2 IngressRoutes. i.e.\n\n  ```sh\n  spk service create my-example-documents-service \\\n    --middlewares middleware \\\n    --k8s-backend-port 3001 \\\n    --k8s-backend docs-service \\\n    --path-prefix documents \\\n    --path-prefix-major-version v2\n  ```\n\n  will result in an IngressRoute that looks like:\n\n  ```yaml\n  apiVersion: traefik.containo.us/v1alpha1\n  kind: IngressRoute\n  metadata:\n    name: my-example-documents-service-master\n  spec:\n    routes:\n      - kind: Rule\n        match: \"PathPrefix(`/v2/documents`) && Headers(`Ring`, `master`)\"\n        middlewares:\n          - name: my-example-documents-service-master\n          - name: middlewareA\n        services:\n          - name: docs-service\n            port: 3001\n  ```\n"
+    "markdown": "## Description\n\nAdd a new service into this initialized spk project repository.\n\n## Example\n\n```bash\nspk service create my-service . \\\n  --display-name $app_name \\\n  --helm-config-path $path_to_chart_in_repo \\\n  --helm-config-git $helm_repo_url \\ # Needs to start with https and not contain user name\n  --helm-config-branch master \\\n  --helm-chart-access-token-variable $ENV_VAR_NAME\n```\n\n## Note\n\n- `--helm-chart-*` and `--helm-config-*` settings are mutually-exclusive. **You\n  may only use one.**\n  - If the git repository referenced in `--helm-config-git` is a private\n    repository, you can specify an environment variable in your\n    HLD-to-Materialized pipeline containing your a PAT to authenticate with via\n    the `--helm-chart-access-token-variable` option.\n- `--middlewares`, `--k8s-backend-port`, `--path-prefix`,\n  `--path-prefix-major-version`, and `--k8s-backend` are all used to configure\n  the generated Traefik2 IngressRoutes. i.e.\n\n  ```sh\n  spk service create my-example-documents-service path/to/my/service \\\n    --middlewares middleware \\\n    --k8s-backend-port 3001 \\\n    --k8s-backend docs-service \\\n    --path-prefix documents \\\n    --path-prefix-major-version v2\n  ```\n\n  will result in an IngressRoute that looks like:\n\n  ```yaml\n  apiVersion: traefik.containo.us/v1alpha1\n  kind: IngressRoute\n  metadata:\n    name: my-example-documents-service-master\n  spec:\n    routes:\n      - kind: Rule\n        match: \"PathPrefix(`/v2/documents`) && Headers(`Ring`, `master`)\"\n        middlewares:\n          - name: my-example-documents-service-master\n          - name: middlewareA\n        services:\n          - name: docs-service\n            port: 3001\n  ```\n"
   },
   "service install-build-pipeline": {
     "command": "install-build-pipeline <service-name>",

guides/auth-private-helm-repos.md

@@ -36,7 +36,7 @@ can make it aware of it via the `--helm-config-access-token-variable` flag in
 the `spk service create` command.
 
 ```sh
-spk service create my-service \
+spk service create my-service ./path/to/service \
   --helm-config-git https://dev.azure.com/my-org/my-project/_git/my-repo \
   --helm-config-branch master \
   --helm-config-path my-service-helm-chart \
@@ -57,8 +57,8 @@ rings:
   master:
     isDefault: true
 services:
-  ./my-service:
-    displayName: ""
+  - path: ./path/to/service
+    displayName: my-service
     helm:
       chart:
         accessTokenVariable: MY_ENV_VAR # Note: this is where the environment variable gets tracked

guides/bedrock-end-to-end-dx.md

@@ -72,21 +72,20 @@ The core `discovery-service` microservice already exists, so he grandfathers it
 into the Bedrock workflow with:
 
 ```bash
-$ spk service create discovery-service -d services
+$ spk service create discovery-service ./path/to/discovery/service -d services
 ```
 
 This updates the bedrock.yaml file to include this service:
 
 ```bash
 $ cat bedrock.yaml
 services:
-    ./services/discovery-service:
-        helm:
-            chart:
-                branch: ''
-                git: ''
-                path: ''
-
+  - path: ./services/discovery-service
+    helm:
+      chart:
+          branch: ''
+          git: ''
+          path: ''
 ```
 
 and adds a `build-update-hld.yaml` file in `services/discovery-service` to build

guides/building-helm-charts-for-spk.md

@@ -38,8 +38,8 @@ rings:
   dev:
     isDefault: true
 services:
-  ./:
-    displayName: "fabrikam"
+  - displayName: "fabrikam"
+    path: ./
     helm:
       chart:
         branch: master
@@ -58,7 +58,7 @@ The above service `fabrikam` was added to `bedrock.yaml` by invoking
 `spk service create` with the requisite parameters ie:
 
 ```sh
-spk service create . \
+spk service create fabrikam . \
 --display-name fabrikam \
 --helm-config-git https://dev.azure.com/fabrikam/frontend/_git/charts \
 --helm-config-path frontend \
@@ -152,9 +152,9 @@ rings:
   dev:
     isDefault: true
 services:
-  ./
-    ...
+  - path: ./
     k8sBackend: 'fabrikam-k8s-svc'
+    ...
 ```
 
 The `serviceName` is generated from a combination of the `k8sBackend`,
@@ -179,7 +179,7 @@ rings:
   dev:
     isDefault: true
 services:
-  ./
+  - path: ./
     ...
     displayName: 'fabrikam'
     k8sBackend: 'fabrikam-k8s-svc'

guides/manual-guide-to-rings.md

@@ -35,7 +35,7 @@ rings:
   qa:
   prod:
 services:
-  ./:
+  - path: ./
     displayName: "fabrikam"
     helm:
       chart:
@@ -87,7 +87,7 @@ rings:
   prod:
   test-new-homepage: <-- NEW -->
 services:
-  ./:
+  - path: ./
     displayName: "fabrikam"
     helm:
       chart:

guides/project-service-management-guide.md

@@ -235,7 +235,7 @@ application repositories
   flag parameters can be used if `spk` was not intialized)
   ```
   SERVICE_NAME=<my-new-service-name>
-  spk service create . --display-name $SERVICE_NAME ...
+  spk service create $SERVICE_NAME . ...
   git add -A
   git commit -m "Adding $SERVICE_NAME to the repository."
   git push -u origin --all
@@ -286,8 +286,8 @@ As an `spk` user, if you would like to incorporate helm charts from a well known
 public repository, you may simply run `spk` the following `helm-chart`
 arguments:
 
-```
-spk service create --helm-chart-chart stable/nginx --helm-chart-repository github.com/helm/charts
+```sh
+spk service create nginx my-nginx-service --helm-chart-chart stable/nginx --helm-chart-repository github.com/helm/charts
 ```
 
 ##### Helm Charts in a distinct Git Repository from Application Sources in the same Azure DevOps Project
@@ -296,7 +296,7 @@ If your Helm Charts are in their own distinct Git Repository in the _same_ Azure
 DevOps project, you can use the `helm-config` arguments to configure `spk`:
 
 ```
-spk service create \
+spk service create fabrikam path/to/fabrikam \
   --helm-config-git https://dev.azure.com/fabrikam/fabrikam-project/_git/fabrikam-helm-charts
   --helm-config-branch master \
   --helm-path /charts/fabrikam
@@ -340,7 +340,7 @@ the environment variable containing the Personal Access Token to access the git
 repository in `helm-config-git`:
 
 ```
-spk service create \
+spk service create fabrikam path/to/fabrikam \
   --helm-config-git https://dev.azure.com/fabrikam/fabrikam-helm-charts-project/_git/fabrikam-helm-charts \
   --helm-config-branch master \
   --helm-path /charts/fabrikam \

guides/rings-101.md

@@ -136,7 +136,7 @@ rings:
     isDefault: false
   qa: {} # isDefault not present is same as isDefault: false
 services:
-  ./my-service-foo:
+  - path: my-service-foo
     displayName: fancy-service
     helm:
       chart:
@@ -212,7 +212,7 @@ rings:
   develop:
     isDefault: false
 services:
-  ./foo:
+  - path: ./foo
     displayName: ""
     helm:
       chart:
@@ -225,7 +225,7 @@ services:
     middlewares: []
     pathPrefix: ""
     pathPrefixMajorVersion: ""
-  ./bar:
+  - path: bar
     displayName: ""
     helm:
       chart:

package.json

@@ -13,7 +13,7 @@
     "md-lint": "find guides -name \\*.md | xargs -n 1 markdown-link-check",
     "format": "prettier --write 'src/**/*.ts{,x}'",
     "test": "jest --rootDir src --reporters=jest-junit --reporters=default --coverage --coverageReporters=cobertura --coverageReporters=html",
-    "test-watch": "jest --watchAll",
+    "test-watch": "jest --rootDir src --watchAll",
     "postinstall": "cd node_modules/azure-devops-node-api && git apply ../../patches/001-azure-devops-node.patch || true",
     "test-coverage-html": "jest --coverage --coverageReporters=html"
   },

src/commands/hld/reconcile.md

@@ -21,7 +21,7 @@ rings:
   master:
     isDefault: true
 services:
-  ./services/fabrikam:
+  - path: ./services/fabrikam
     displayName: "fabrikam"
     k8sBackendPort: 8001
     k8sBackend: "fabrikam-k8s-svc"