code updates

Author: Sagar-Talikoti

bin/mas-devops-feature-status-update

@@ -35,7 +35,7 @@ Sub-commands
     Required indexes are created automatically on the first call if they do
     not already exist (idempotent).
 
-    Example — instance-level, ACTIVE:
+    Example — instance-level, ACTIVE (single IP):
       mas-devops-feature-status-update status-update \\
           --region     us-east-2 \\
           --instance-id inst02 \\
@@ -49,27 +49,46 @@ Sub-commands
           --deployment-start 2026-09-11T11:48:42+00:00 \\
           --deployment-end   2026-09-11T11:53:10+00:00
 
-    Example — cluster-level (no --instance-id), ERROR:
+    Example — instance-level, ACTIVE (multiple IPs):
       mas-devops-feature-status-update status-update \\
           --region     us-east-2 \\
+          --instance-id inst02 \\
           --account    fyre-noble10-dev \\
           --cluster    noble10 \\
           --subscription-id sub-id01 \\
           --type       allow-list \\
-          --feature-details '{"ips": ["2405:201:d000:9062::/64"]}' \\
+          --feature-details '{"ips": ["1.2.3.4/32", "2405:201:d000:9062::/64"]}' \\
+          --status     ACTIVE \\
+          --status-details '{"message": "Allow list is active.", "request_configuration": "1.2.3.4/32, 2405:201:d000:9062::/64"}' \\
+          --deployment-start 2026-09-11T11:48:42+00:00 \\
+          --deployment-end   2026-09-11T11:53:10+00:00
+
+    Example — instance-level, ERROR (using --status-details-file to avoid shell quoting issues):
+      cat > /tmp/status-details.json <<'EOF'
+      {
+        "message": "sample error message",
+        "error_code": 401,
+        "error_source": {
+          "gitops_version": "8.6.0",
+          "filename": "cis_ip_allowlist.yml",
+          "log_file": "/var/log/gitops/run-001.log",
+          "stacktrace": "Traceback (most recent call last): ..."
+        },
+        "request_configuration": "2405:201:d000:9060::/64"
+      }
+      EOF
+      mas-devops-feature-status-update status-update \\
+          --region     us-east-2 \\
+          --instance-id inst02 \\
+          --account    fyre-noble10-dev \\
+          --cluster    noble10 \\
+          --subscription-id sub-id01 \\
+          --type       allow-list \\
+          --feature-details '{"ips": ["2405:201:d000:9060::/64"]}' \\
           --status     ERROR \\
-          --status-details '{
-            "message": "sample error message",
-            "error_code": 401,
-            "error_source": {
-              "gitops_version": "8.6.0",
-              "filename": "cis_ip_allowlist.yml",
-              "line_no": 148,
-              "log_file": "/var/log/gitops/run-001.log",
-              "stacktrace": "Traceback (most recent call last): ..."
-            },
-            "request_configuration": "2405:201:d000:9060::/64"
-          }'
+          --status-details-file /tmp/status-details.json \\
+          --deployment-start 2026-09-11T11:48:42+00:00 \\
+          --deployment-end   2026-09-11T11:53:10+00:00
 
   get
     Fetch and pretty-print a feature status entry by ObjectId or by
@@ -163,6 +182,19 @@ def _parse_json_arg(value: str, arg_name: str) -> dict:
     return result
 
 
+def _read_file_arg(path: str, arg_name: str) -> str:
+    """Read and return the contents of *path* for use as a CLI argument value.
+
+    Raises SystemExit(1) if the file cannot be read.
+    """
+    try:
+        with open(path) as fh:
+            return fh.read()
+    except OSError as exc:
+        print(f"ERROR: --{arg_name}: cannot read file '{path}': {exc}", file=sys.stderr)
+        sys.exit(1)
+
+
 def _parse_isodate(value: Optional[str], arg_name: str) -> Optional[datetime]:
     """Parse an ISO-8601 datetime, stripping MongoDB ISODate() wrappers."""
     if value is None:
@@ -301,8 +333,8 @@ def cmd_status_update(args) -> int:
     """Upsert a feature status entry into MongoDB.
 
     Collection routing is determined by FEATURE_LEVEL_MAP:
-      INSTANCE_LEVEL → instance_level_config  (--instance-id required)
-      otherwise      → cluster_level_config   (--instance-id must be absent)
+      INSTANCE_LEVEL → instance_level_config  (--instance-id and --subscription-id required)
+      otherwise      → cluster_level_config   (--instance-id and --subscription-id must be absent)
 
     Required indexes are created automatically if they do not already exist.
     """
@@ -330,17 +362,24 @@ def cmd_status_update(args) -> int:
         print(f"ERROR: {exc}", file=sys.stderr)
         return 1
 
-    # Validate --instance-id consistency with the feature type's level.
+    # Validate --instance-id / --subscription-id consistency with the feature type's level.
     if level == INSTANCE_LEVEL and not args.instance_id:
         print(f"ERROR: --instance-id is required for instance-level feature type '{args.type}'", file=sys.stderr)
         return 1
+    if level == INSTANCE_LEVEL and not args.subscription_id:
+        print(f"ERROR: --subscription-id is required for instance-level feature type '{args.type}'", file=sys.stderr)
+        return 1
     if level != INSTANCE_LEVEL and args.instance_id:
         print(f"ERROR: --instance-id must not be supplied for cluster-level feature type '{args.type}'", file=sys.stderr)
         return 1
 
-    # Parse JSON arguments
+    # Parse JSON arguments — --status-details-file takes precedence over --status-details
     feature_details = _parse_json_arg(args.feature_details, "feature-details")
-    status_details = _parse_json_arg(args.status_details, "status-details")
+    if args.status_details_file:
+        status_details_raw = _read_file_arg(args.status_details_file, "status-details-file")
+        status_details = _parse_json_arg(status_details_raw, "status-details-file")
+    else:
+        status_details = _parse_json_arg(args.status_details, "status-details")
 
     # Type-specific validation
     try:
@@ -462,7 +501,13 @@ def build_parser() -> argparse.ArgumentParser:
     )
     identity.add_argument("--account", required=True, help="GitOps account name (e.g. fyre-noble10-dev)")
     identity.add_argument("--cluster", required=True, help="GitOps cluster name (e.g. noble10)")
-    identity.add_argument("--subscription-id", required=True, dest="subscription_id", help="Subscription ID")
+    identity.add_argument(
+        "--subscription-id",
+        required=False,
+        default=None,
+        dest="subscription_id",
+        help="Subscription ID. Required for instance-level feature types; must be omitted for cluster-level types.",
+    )
 
     feature = su.add_argument_group("feature")
     feature.add_argument(
@@ -485,15 +530,30 @@ def build_parser() -> argparse.ArgumentParser:
         choices=["REQUESTED", "IN_PROGRESS", "ACTIVE", "ERROR"],
         help="Feature lifecycle status.",
     )
-    status.add_argument(
+    status_details_group = status.add_mutually_exclusive_group(required=True)
+    status_details_group.add_argument(
         "--status-details",
-        required=True,
+        default=None,
         dest="status_details",
         metavar="JSON",
         help=(
             "JSON object describing the outcome. "
-            "ACTIVE: {message, request_configuration}. "
-            "ERROR: {message, error_code, error_source, request_configuration}."
+            "ACTIVE/REQUESTED/IN_PROGRESS: {message, request_configuration}. "
+            "ERROR: {message, error_code, error_source, request_configuration}. "
+            "request_configuration may be a single CIDR or a comma/space-separated list. "
+            "Mutually exclusive with --status-details-file."
+        ),
+    )
+    status_details_group.add_argument(
+        "--status-details-file",
+        default=None,
+        dest="status_details_file",
+        metavar="FILE",
+        help=(
+            "Path to a JSON file containing the status-details object. "
+            "Useful for ERROR payloads whose message or stacktrace contains quotes "
+            "that would break inline shell quoting. "
+            "Mutually exclusive with --status-details."
         ),
     )
 

bin/mas-devops-feature-status-update.md

@@ -142,15 +142,15 @@ Required collection indexes (`instance_config_level`, `cluster_config_level`) ar
 
 **Idempotency:** Safe to call multiple times with the same arguments. The underlying `find_one_and_update` with `upsert=True` guarantees that re-running with the same identity key produces the same final document state. `created_at` is set only on the first insert (`$setOnInsert`); subsequent calls update `updated_at` and all mutable fields without creating duplicate documents.
 
-**Identity options** *(all required)*
+**Identity options**
 
-| Flag | Description |
-|------|-------------|
-| `--region` | AWS region (e.g. `us-east-2`) |
-| `--instance-id` | MAS instance ID (e.g. `inst02`) |
-| `--account` | GitOps account name (e.g. `fyre-noble10-dev`) |
-| `--cluster` | GitOps cluster name (e.g. `noble10`) |
-| `--subscription-id` | Subscription ID |
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--region` | Yes | AWS region (e.g. `us-east-2`) |
+| `--instance-id` | Instance-level types | MAS instance ID (e.g. `inst02`). When supplied routes to `instance_level_config`; when omitted routes to `cluster_level_config`. |
+| `--account` | Yes | GitOps account name (e.g. `fyre-noble10-dev`) |
+| `--cluster` | Yes | GitOps cluster name (e.g. `noble10`) |
+| `--subscription-id` | Instance-level types | Subscription ID. Required when `--instance-id` is supplied; must be omitted for cluster-level feature types. |
 
 **Feature options** *(all required)*
 
@@ -164,7 +164,8 @@ Required collection indexes (`instance_config_level`, `cluster_config_level`) ar
 | Flag | Description |
 |------|-------------|
 | `--status` | One of `REQUESTED`, `IN_PROGRESS`, `ACTIVE`, `ERROR` |
-| `--status-details JSON` | JSON object describing the outcome (see schema below) |
+| `--status-details JSON` | JSON object describing the outcome (see schema below). Mutually exclusive with `--status-details-file`. |
+| `--status-details-file FILE` | Path to a JSON file containing the status-details object. Use this for `ERROR` payloads whose `message` or `stacktrace` contains quote characters that would break inline shell interpolation. Mutually exclusive with `--status-details`. |
 
 **Timestamp options** *(all optional, default: current UTC time)*
 
@@ -179,6 +180,8 @@ The MongoDB connection URI is read from the `DEVOPS_MONGO_URI` environment varia
 
 **`--status-details` schema**
 
+`request_configuration` is a free-form string describing what was requested — it may be a single CIDR, a comma-separated list, or a space-separated list. The validator does not enforce format.
+
 *REQUESTED* — pipeline has received the request but processing has not yet started.
 ```json
 {
@@ -195,23 +198,22 @@ The MongoDB connection URI is read from the `DEVOPS_MONGO_URI` environment varia
 }
 ```
 
-*ACTIVE* — deployment completed successfully.
+*ACTIVE* — deployment completed successfully. Multiple IPs may be comma-separated.
 ```json
 {
   "message": "Allow list is active.",
-  "request_configuration": "2405:201:d000:9062::/64"
+  "request_configuration": "1.2.3.4/32, 2405:201:d000:9062::/64"
 }
 ```
 
-*ERROR* — deployment failed.
+*ERROR* — deployment failed. `error_source` fields are all optional except that the object itself is required. Use `--status-details-file` when `message` or `stacktrace` may contain quote characters.
 ```json
 {
   "message": "sample error message",
   "error_code": 401,
   "error_source": {
     "gitops_version": "8.6.0",
     "filename": "cis_ip_allowlist.yml",
-    "line_no": 148,
     "log_file": "/var/log/gitops/run-001.log",
     "stacktrace": "Traceback (most recent call last): ..."
   },
@@ -248,7 +250,7 @@ mas-devops-feature-status-update status-update \
     --status-details '{"message": "Allow list deployment in progress.", "request_configuration": "2405:201:d000:9062::/64"}' \
     --deployment-start 2026-09-11T11:48:42+00:00
 
-# ACTIVE status — record successful completion
+# ACTIVE status — single IP
 mas-devops-feature-status-update status-update \
     --region us-east-2 \
     --instance-id inst02 \
@@ -262,28 +264,44 @@ mas-devops-feature-status-update status-update \
     --deployment-start 2026-09-11T11:48:42+00:00 \
     --deployment-end   2026-09-11T11:53:10+00:00
 
-# ERROR status — record a failed deployment
+# ACTIVE status — multiple IPs (request_configuration is comma-separated)
 mas-devops-feature-status-update status-update \
     --region us-east-2 \
     --instance-id inst02 \
     --account fyre-noble10-dev \
     --cluster noble10 \
     --subscription-id sub-id01 \
     --type allow-list \
-    --feature-details '{"ips": ["2405:201:d000:9062::/64"]}' \
+    --feature-details '{"ips": ["1.2.3.4/32", "2405:201:d000:9062::/64"]}' \
+    --status ACTIVE \
+    --status-details '{"message": "Allow list is active.", "request_configuration": "1.2.3.4/32, 2405:201:d000:9062::/64"}' \
+    --deployment-start 2026-09-11T11:48:42+00:00 \
+    --deployment-end   2026-09-11T11:53:10+00:00
+
+# ERROR status — use --status-details-file to avoid shell quoting issues with error text
+cat > /tmp/status-details.json <<'EOF'
+{
+  "message": "sample error message",
+  "error_code": 401,
+  "error_source": {
+    "gitops_version": "8.6.0",
+    "filename": "cis_ip_allowlist.yml",
+    "log_file": "/var/log/gitops/run-001.log",
+    "stacktrace": "Traceback (most recent call last): ..."
+  },
+  "request_configuration": "2405:201:d000:9060::/64"
+}
+EOF
+mas-devops-feature-status-update status-update \
+    --region us-east-2 \
+    --instance-id inst02 \
+    --account fyre-noble10-dev \
+    --cluster noble10 \
+    --subscription-id sub-id01 \
+    --type allow-list \
+    --feature-details '{"ips": ["2405:201:d000:9060::/64"]}' \
     --status ERROR \
-    --status-details '{
-      "message": "sample error message",
-      "error_code": 401,
-      "error_source": {
-        "gitops_version": "8.6.0",
-        "filename": "cis_ip_allowlist.yml",
-        "line_no": 148,
-        "log_file": "/var/log/gitops/run-001.log",
-        "stacktrace": "Traceback (most recent call last): ..."
-      },
-      "request_configuration": "2405:201:d000:9060::/64"
-    }' \
+    --status-details-file /tmp/status-details.json \
     --deployment-start 2026-09-11T11:48:42+00:00 \
     --deployment-end   2026-09-11T11:53:10+00:00
 ```
@@ -414,6 +432,16 @@ db.cluster_level_config.drop()
 db.instance_level_config.drop()
 ```
 
+### Drop collections (removes schema & indexes) with auth
+```
+mongosh "mongodb://mas_devops_user:mas_devops_password@localhost:27017/mas_devops?authSource=mas_devops&tls=false&tlsAllowInvalidCertificates=true" \  # pragma: allowlist secret
+  --eval "
+db.cluster_level_config.drop()
+db.instance_level_config.drop()
+print('collections dropped')
+"
+```
+
 > **Note:** `drop()` removes the collection, all documents, and all indexes. Re-run `init_db.js` to recreate them.
 
 ### Indexes created by `init_db.js`
@@ -505,6 +533,44 @@ See the full sample playbook at [`playbooks/feature-status-update.yml`](../playb
   changed_when: "'written successfully' in status_update_result.stdout"
 ```
 
+For `ERROR` status, write the payload to a file first to avoid shell quoting problems with error text:
+
+```yaml
+- name: Write ERROR status-details to file
+  ansible.builtin.copy:
+    dest: /tmp/mas-status-details.json
+    content: |
+      {
+        "message": "{{ _error_msg | replace('\\', '\\\\') | replace('"', '\\"') }}",
+        "error_code": {{ _error_code }},
+        "error_source": {
+          "gitops_version": "{{ lookup('env', 'GITOPS_VERSION') | default('', true) }}",
+          "filename": "{{ _error_filename }}",
+          "log_file": "{{ lookup('env', 'JUNIT_OUTPUT_DIR') | default('/var/log/gitops', true) }}/run.log",
+          "stacktrace": "{{ _error_msg | replace('\\', '\\\\') | replace('"', '\\"') }}"
+        },
+        "request_configuration": "{{ _request_configuration }}"
+      }
+
+- name: Upsert feature status (ERROR)
+  ansible.builtin.command:
+    cmd: >-
+      mas-devops-feature-status-update status-update
+      --region {{ mas_region }}
+      --instance-id {{ mas_instance_id }}
+      --account {{ mas_account }}
+      --cluster {{ mas_cluster }}
+      --subscription-id {{ mas_subscription_id }}
+      --type allow-list
+      --feature-details {{ ('{"ips": ' + _normalised_ips | to_json + '}') | quote }}
+      --status ERROR
+      --status-details-file /tmp/mas-status-details.json
+      --deployment-start {{ _deployment_start }}
+      --deployment-end {{ _deployment_end }}
+  register: status_update_result
+  changed_when: "'written successfully' in status_update_result.stdout"
+```
+
 ### Minimal task — `get`
 
 **By ObjectId** — extract the document ID from `status-update` output and fetch the written document: