From ae59f0714116b29603d78e74979fcdd81c193fa6 Mon Sep 17 00:00:00 2001 From: Dan Miller Date: Mon, 11 Mar 2024 10:39:05 -0700 Subject: [PATCH] feat: `prettier` in READMEs (https://github.com/cloudposse/terraform-aws-components/pull/998) --- src/CHANGELOG.md | 13 ++--- src/README.md | 91 ++++++++++++++++++------------- src/modules/escalation/README.md | 6 +- src/modules/integration/README.md | 2 + src/modules/routing/README.md | 7 ++- 5 files changed, 69 insertions(+), 50 deletions(-) diff --git a/src/CHANGELOG.md b/src/CHANGELOG.md index ed8ac39..209f811 100644 --- a/src/CHANGELOG.md +++ b/src/CHANGELOG.md @@ -2,15 +2,12 @@ ### `team` replaced with `team_options` -The `team` variable has been replaced with `team_options` to reduce confusion. -The component only ever creates at most one team, with the name -specified in the `name` variable. The `team` variable was introduced to -provide a single object to specify other options, but was not implemented -properly. +The `team` variable has been replaced with `team_options` to reduce confusion. The component only ever creates at most +one team, with the name specified in the `name` variable. The `team` variable was introduced to provide a single object +to specify other options, but was not implemented properly. ### Team membership now managed by this component by default -Previously, the default behavior was to not manage team membership, -allowing users to be managed via the Opsgenie UI. Now the default is to manage -via the `members` input. To restore the previous behavior, set +Previously, the default behavior was to not manage team membership, allowing users to be managed via the Opsgenie UI. +Now the default is to manage via the `members` input. To restore the previous behavior, set `team_options.ignore_members` to `true`. diff --git a/src/README.md b/src/README.md index cdcd659..06ee770 100644 --- a/src/README.md +++ b/src/README.md @@ -5,29 +5,32 @@ This component is responsible for provisioning Opsgenie teams and related servic ## Usage #### Pre-requisites -You need an API Key stored in `/opsgenie/opsgenie_api_key` of SSM, this is configurable using the `ssm_parameter_name_format` and `ssm_path` variables. -Opsgenie is now part of Atlassian, so you need to make sure you are creating -an Opsgenie API Key, which looks like `abcdef12-3456-7890-abcd-ef0123456789` -and not an Atlassian API key, which looks like +You need an API Key stored in `/opsgenie/opsgenie_api_key` of SSM, this is configurable using the +`ssm_parameter_name_format` and `ssm_path` variables. + +Opsgenie is now part of Atlassian, so you need to make sure you are creating an Opsgenie API Key, which looks like +`abcdef12-3456-7890-abcd-ef0123456789` and not an Atlassian API key, which looks like ```shell ATAfT3xFfGF0VFXAfl8EmQNPVv1Hlazp3wsJgTmM8Ph7iP-RtQyiEfw-fkDS2LvymlyUOOhc5XiSx46vQWnznCJolq-GMX4KzdvOSPhEWr-BF6LEkJQC4CSjDJv0N7d91-0gVekNmCD2kXY9haUHUSpO4H7X6QxyImUb9VmOKIWTbQi8rf4CF28=63CB21B9 ``` -Generate an API Key by going to Settings -> API key management on your Opsgenie -control panel, which will have an address like `https://.app.opsgenie.com/settings/api-key-management`, -and click the "Add new API key" button. For more information, see the +Generate an API Key by going to Settings -> API key management on your Opsgenie control panel, which will have an +address like `https://.app.opsgenie.com/settings/api-key-management`, and click the "Add new API key" button. +For more information, see the [Opsgenie API key management documentation](https://support.atlassian.com/opsgenie/docs/api-key-management/). -Once you have the key, you'll need to test it with a curl to verify that you are at least -on a Standard plan with OpsGenie: +Once you have the key, you'll need to test it with a curl to verify that you are at least on a Standard plan with +OpsGenie: + ``` curl -X GET 'https://api.opsgenie.com/v2/account' \ --header "Authorization: GenieKey $API_KEY" ``` The result should be something similar to below: + ``` { "data": { @@ -39,9 +42,8 @@ The result should be something similar to below: } ``` -If you see `Free` or `Essentials` in the plan, then you won't be able -to use this component. You can see more details here: -[OpsGenie pricing/features](https://www.atlassian.com/software/opsgenie/pricing#) +If you see `Free` or `Essentials` in the plan, then you won't be able to use this component. You can see more details +here: [OpsGenie pricing/features](https://www.atlassian.com/software/opsgenie/pricing#) #### Getting Started @@ -49,7 +51,8 @@ to use this component. You can see more details here: Here's an example snippet for how to use this component. -This component should only be applied once as the resources it creates are regional, but it works with integrations. This is typically done via the auto or corp stack (e.g. `gbl-auto.yaml`). +This component should only be applied once as the resources it creates are regional, but it works with integrations. +This is typically done via the auto or corp stack (e.g. `gbl-auto.yaml`). ```yaml # 9-5 Mon-Fri @@ -175,8 +178,8 @@ components: notify_type: default delay: 60 recipients: - - type: team - name: otherteam + - type: team + name: otherteam yaep_escalation: enabled: true @@ -187,8 +190,8 @@ components: notify_type: default delay: 90 recipients: - - type: user - name: user@example.com + - type: user + name: user@example.com schedule_escalation: enabled: true @@ -199,8 +202,8 @@ components: notify_type: default delay: 30 recipients: - - type: schedule - name: secondary_on_call + - type: schedule + name: secondary_on_call ``` The API keys relating to the Opsgenie Integrations are stored in SSM Parameter Store and can be accessed via chamber. @@ -210,13 +213,18 @@ AWS_PROFILE=foo chamber list opsgenie-team/ ``` ### ClickOps Work - - After deploying the opsgenie-team component the created team will have a schedule named after the team. This is purposely left to be clickOps’d so the UI can be used to set who is on call, as that is the usual way (not through code). Additionally, we do not want a re-apply of the Terraform to delete or shuffle who is planned to be on call, thus we left who is on-call on a schedule out of the component. + +- After deploying the opsgenie-team component the created team will have a schedule named after the team. This is + purposely left to be clickOps’d so the UI can be used to set who is on call, as that is the usual way (not through + code). Additionally, we do not want a re-apply of the Terraform to delete or shuffle who is planned to be on call, + thus we left who is on-call on a schedule out of the component. ## Known Issues ### Different API Endpoints in Use The problem is there are 3 different api endpoints in use + - `/webapp` - the most robust - only exposed to the UI (that we've seen) - `/v2/` - robust with some differences from `webapp` - `/v1/` - the oldest and furthest from the live UI. @@ -231,11 +239,11 @@ This module does not create users. Users must have already been created to be ad ### Cannot Add Stakeholders - - Track the issue: https://github.com/opsgenie/terraform-provider-opsgenie/issues/278 +- Track the issue: https://github.com/opsgenie/terraform-provider-opsgenie/issues/278 ### No Resource to create Slack Integration - - Track the issue: https://github.com/DataDog/terraform-provider-datadog/issues/67 +- Track the issue: https://github.com/DataDog/terraform-provider-datadog/issues/67 ### Out of Date Terraform Docs @@ -244,10 +252,12 @@ Another Problem is the terraform docs are not always up to date with the provide The OpsGenie Provider uses a mix of `/v1` and `/v2`. This means there are many things you can only do from the UI. Listed below in no particular order -- Incident Routing cannot add dependent services - in `v1` and `v2` a `service_incident_rule` object has `serviceId` as type string, in webapp this becomes `serviceIds` of type `list(string)` + +- Incident Routing cannot add dependent services - in `v1` and `v2` a `service_incident_rule` object has `serviceId` as + type string, in webapp this becomes `serviceIds` of type `list(string)` - Opsgenie Provider appears to be inconsistent with how it uses `time_restriction`: - - `restrictions` for type `weekday-and-time-of-day` - - `restriction` for type `time-of-day` + - `restrictions` for type `weekday-and-time-of-day` + - `restriction` for type `time-of-day` Unfortunately none of this is in the terraform docs, and was found via errors and digging through source code. @@ -259,24 +269,27 @@ We recommend to use the human readable timezone such as `Europe/London`. - Setting a schedule to a GMT-style timezone with offsets can cause inconsistent plans. - Setting the timezone to `Etc/GMT+1` instead of `Europe/London`, will lead to permadrift as OpsGenie converts the GMT offsets to regional timezones at deploy-time. In the previous deploy, the GMT style get converted to `Atlantic/Cape_Verde`. + Setting the timezone to `Etc/GMT+1` instead of `Europe/London`, will lead to permadrift as OpsGenie converts the GMT + offsets to regional timezones at deploy-time. In the previous deploy, the GMT style get converted to + `Atlantic/Cape_Verde`. - ```hcl - # module.routing["london_schedule"].module.team_routing_rule[0].opsgenie_team_routing_rule.this[0] will be updated in-place - ~ resource "opsgenie_team_routing_rule" "this" { - id = "4b4c4454-8ccf-41a9-b856-02bec6419ba7" - name = "london_schedule" - ~ timezone = "Atlantic/Cape_Verde" -> "Etc/GMT+1" - # (2 unchanged attributes hidden) - ``` + ```hcl + # module.routing["london_schedule"].module.team_routing_rule[0].opsgenie_team_routing_rule.this[0] will be updated in-place + ~ resource "opsgenie_team_routing_rule" "this" { + id = "4b4c4454-8ccf-41a9-b856-02bec6419ba7" + name = "london_schedule" + ~ timezone = "Atlantic/Cape_Verde" -> "Etc/GMT+1" + # (2 unchanged attributes hidden) + ``` - Some GMT styles will not cause a timezone change on subsequent applies such as `Etc/GMT+8` for `Asia/Taipei`. + Some GMT styles will not cause a timezone change on subsequent applies such as `Etc/GMT+8` for `Asia/Taipei`. -- If the calendar date has crossed daylight savings time, the `Etc/GMT+` GMT style will need to be updated to reflect the correct timezone. +- If the calendar date has crossed daylight savings time, the `Etc/GMT+` GMT style will need to be updated to reflect + the correct timezone. Track the issue: https://github.com/opsgenie/terraform-provider-opsgenie/issues/258 - + ## Requirements @@ -370,6 +383,7 @@ Track the issue: https://github.com/opsgenie/terraform-provider-opsgenie/issues/ | [team\_members](#output\_team\_members) | Team members | | [team\_name](#output\_team\_name) | Team Name | + ## Related How-to Guides @@ -383,7 +397,8 @@ Track the issue: https://github.com/opsgenie/terraform-provider-opsgenie/issues/ - [How to Implement Incident Management with OpsGenie](https://docs.cloudposse.com/reference-architecture/how-to-guides/tutorials/how-to-implement-incident-management-with-opsgenie) ## References -* [cloudposse/terraform-aws-components](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/opsgenie-team) - Cloud Posse's upstream component +- [cloudposse/terraform-aws-components](https://github.com/cloudposse/terraform-aws-components/tree/main/modules/opsgenie-team) - + Cloud Posse's upstream component [](https://cpco.io/component) diff --git a/src/modules/escalation/README.md b/src/modules/escalation/README.md index e5261df..d578626 100644 --- a/src/modules/escalation/README.md +++ b/src/modules/escalation/README.md @@ -1,7 +1,7 @@ ## Escalation -Terraform module to configure [Opsgenie Escalation](https://registry.terraform.io/providers/opsgenie/opsgenie/latest/docs/resources/escalation) - +Terraform module to configure +[Opsgenie Escalation](https://registry.terraform.io/providers/opsgenie/opsgenie/latest/docs/resources/escalation) ## Usage @@ -27,6 +27,7 @@ module "escalation" { } ``` + ## Requirements @@ -89,3 +90,4 @@ module "escalation" { | [escalation\_id](#output\_escalation\_id) | The ID of the Opsgenie Escalation | | [escalation\_name](#output\_escalation\_name) | Name of the Opsgenie Escalation | + diff --git a/src/modules/integration/README.md b/src/modules/integration/README.md index 21faa8b..fe7b0a1 100644 --- a/src/modules/integration/README.md +++ b/src/modules/integration/README.md @@ -2,6 +2,7 @@ This module creates an OpsGenie integrations for a team. By Default, it creates a Datadog integration. + ## Requirements @@ -67,3 +68,4 @@ This module creates an OpsGenie integrations for a team. By Default, it creates | [ssm\_path](#output\_ssm\_path) | Full SSM path of the team integration key | | [type](#output\_type) | Type of the team integration | + diff --git a/src/modules/routing/README.md b/src/modules/routing/README.md index bf6f145..a69fa1d 100644 --- a/src/modules/routing/README.md +++ b/src/modules/routing/README.md @@ -1,8 +1,10 @@ ## Routing -This module creates team routing rules, these are the initial rules that are applied to an alert to determine who gets notified. -This module also creates incident service rules, which determine if an alert is considered a service incident or not. +This module creates team routing rules, these are the initial rules that are applied to an alert to determine who gets +notified. This module also creates incident service rules, which determine if an alert is considered a service incident +or not. + ## Requirements @@ -76,3 +78,4 @@ This module also creates incident service rules, which determine if an alert is | [service\_incident\_rule](#output\_service\_incident\_rule) | Service incident rules for incidents | | [team\_routing\_rule](#output\_team\_routing\_rule) | Team routing rules for alerts | +