背景
下記URLの通り、分析テンプレートのカスタマイズは普通に Documented なのですが、技術力の無い僕ははまってしまったので、はまったポイントをメモっておきます。誰かの役に立てたらいいな。
https://docs.aws.amazon.com/ja_jp/incident-manager/latest/userguide/analysis.html#analysis-templates
Step1. 標準テンプレートをダウンロードする。
デフォルトが json 形式とのことなので、.json という名前で保存してみる。
aws-cli
[ec2-user@ip-172-31-1-202 ~]$ aws ssm get-document --name AWSIncidents-PostIncidentAnalysisTemplate > ./AWSIncidents-PostIncidentAnalysisTemplate.json
Content の中に【How could time to detection be improved? As a thought exercise, how would you cut the time in half?】とかの文字があるので、Content の中を更新した別ファイルを作ってアップロード(create-document)すればよさそう。と思われた。
出力結果
[ec2-user@ip-172-31-1-202 ~]$ cat AWSIncidents-PostIncidentAnalysisTemplate.json {
"Name": "AWSIncidents-PostIncidentAnalysisTemplate",
"CreatedDate": "2021-05-07T18:11:36.934000+00:00",
"DocumentVersion": "1",
"Status": "Active",
"Content": "{\n \"sections\": [\n {\n \"id\": \"overview\",\n \"name\": \"Overview\",\n \"components\": [\n {\n \"questions\": {\n \"title\": \"Summary\",\n \"description\": \"Provide a summary of the incident, include the following; what happened, why it happened, how it was mitigated, and what is being done about it at a high level.\",\n \"questions\": [\n {\n \"id\": \"S1\",\n \"answer\": {\n \"markdown\": {\n }\n }\n }\n ]\n }\n },\n {\n \"questions\": {\n \"title\": \"Impact\",\n \"description\": \"A 1-2 paragraph summary of the customer-facing impact (or experience) during the event. Do not mention customers by name in this section. Provide explicit figures to detail the blast radius.\",\n \"questions\": [\n {\n \"id\": \"I1\",\n \"answer\": {\n \"markdown\": {\n }\n }\n }\n ]\n }\n }\n ]\n },\n {\n \"id\": \"metrics\",\n \"name\": \"Metrics\",\n \"components\": [\n {\n \"metrics\": {\n \"title\": \"Metrics\",\n \"description\": \"Metrics with detailed information about impact. When available, metrics from related incidents are imported and displayed here.\"\n }\n }\n ]\n },\n {\n \"id\": \"timeline\",\n \"name\": \"Timeline\",\n \"components\": [\n {\n \"timeline\": {\n }\n }\n ]\n },\n {\n \"id\": \"questions\",\n \"name\": \"Incident questions\",\n \"components\": [\n {\n \"questions\": {\n \"title\": \"Detection\",\n \"description\": \"The following questions help guide your team to detect incidents more effectively.\",\n \"questions\": [\n {\n \"id\": \"ID1\",\n \"title\": \"How could time to detection be improved? As a thought exercise, how would you cut the time in half?\",\n \"answer\": {\n \"text\": {\n }\n }\n },\n {\n \"id\": \"ID2\",\n \"title\": \"What adjustments could be made to the metrics used for detection?\",\n \"answer\": {\n \"pair\": {\n \"left\": {\n \"description\": \"Adjustments\",\n \"multiSelect\": {\n \"items\": [\n {\n \"value\": \"Add metric\",\n \"recommendation\": {\n \"id\": \"amzn-add-metric\",\n \"title\": \"Add detection metric\",\n \"description\": \"Create or update a CloudWatch metric\",\n \"size\": \"MEDIUM\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Update resolution\",\n \"recommendation\": {\n \"id\": \"amzn-update-resolution\",\n \"title\": \"Update detection metric resolution\",\n \"description\": \"Create or update a CloudWatch metric\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Improve quality of data\",\n \"recommendation\": {\n \"id\": \"amzn-improve-quality-of-data\",\n \"title\": \"Improve the quality of detection metric data\",\n \"description\": \"Create or update a CloudWatch metric\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Other\"\n },\n {\n \"value\": \"No actions needed\"\n }\n ]\n }\n },\n \"right\": {\n \"description\": \"Comments\",\n \"optional\": true,\n \"text\": {\n }\n }\n }\n }\n },\n {\n \"id\": \"ID3\",\n \"title\": \"What adjustments could be made to the alarms used for detection?\",\n \"answer\": {\n \"pair\": {\n \"left\": {\n \"description\": \"Adjustments\",\n \"multiSelect\": {\n \"items\": [\n {\n \"value\": \"Add alarm\",\n \"recommendation\": {\n \"id\": \"amzn-add-alarm\",\n \"title\": \"Add detection alarm\",\n \"description\": \"Create or update a CloudWatch alarm\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Update threshold\",\n \"recommendation\": {\n \"id\": \"amzn-update-threshold\",\n \"title\": \"Update detection alarm theshold\",\n \"description\": \"Create or update a CloudWatch alarm\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Update severity\",\n \"recommendation\": {\n \"id\": \"amzn-update-severity\",\n \"title\": \"Update detection alarm severity\",\n \"description\": \"Create or update a CloudWatch alarm\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Other\"\n },\n {\n \"value\": \"No adjustments needed\"\n }\n ]\n }\n },\n \"right\": {\n \"description\": \"Comments\",\n \"optional\": true,\n \"text\": {\n }\n }\n }\n }\n }\n ]\n }\n },\n {\n \"questions\": {\n \"title\": \"Diagnosis\",\n \"description\": \"The following questions help guide your team to triage incidents more effectively.\",\n \"questions\": [\n {\n \"id\": \"DN1\",\n \"title\": \"How could time to diagnosis be improved? As a thought exercise, how would you cut the time in half?\",\n \"answer\": {\n \"text\": {\n }\n }\n },\n {\n \"id\": \"DN2\",\n \"title\": \"Do any of the following need to be updated to engage the correct contact faster?\",\n \"answer\": {\n \"pair\": {\n \"left\": {\n \"description\": \"Resource\",\n \"multiSelect\": {\n \"items\": [\n {\n \"value\": \"Escalation plan\",\n \"recommendation\": {\n \"id\": \"amzn-update-escalation-plan\",\n \"title\": \"Update escalation plan\",\n \"description\": \"Create or update escalation plan\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Steps in response plan\",\n \"recommendation\": {\n \"id\": \"amzn-update-response-plan\",\n \"title\": \"Update response plan\",\n \"description\": \"Create or update response plan\",\n \"size\": \"SMALL\",\n \"priority\": \"HIGH\"\n }\n },\n {\n \"value\": \"Other\"\n },\n {\n \"value\": \"No updates needed\"\n }\n ]\n }\n },\n \"right\": {\n \"description\": \"Comments\",\n \"optional\": true,\n \"text\": {\n }\n }\n }\n }\n }\n ]\n }\n },\n {\n \"questions\": {\n \"title\": \"Mitigation\",\n \"description\": \"The following questions investigate ways to decrease MTTR.\",\n \"questions\": [\n {\n \"id\": \"MT1\",\n \"title\": \"How could time to mitigation be improved? As a thought exercise, how would you cut the time in half?\",\n \"answer\": {\n \"text\": {\n }\n }\n },\n {\n \"id\": \"MT2\",\n \"title\": \"Could the runbook for the incident be improved? Did the runbook contain unnecessary steps or lack ones that would help?\",\n \"answer\": {\n \"pair\": {\n \"left\": {\n \"singleSelect\": {\n \"items\": [\n {\n \"value\": \"N/A\"\n },\n {\n \"value\": \"No\"\n },\n {\n \"value\": \"Yes\",\n \"recommendation\": {\n \"id\": \"amzn-update-runbook\",\n \"title\": \"Update incident runbook\",\n \"description\": \"Create or update runbook\",\n \"priority\": \"HIGH\",\n \"size\": \"SMALL\"\n }\n }\n ]\n }\n },\n \"right\": {\n \"description\": \"Comments\",\n \"optional\": true,\n \"text\": {\n }\n }\n }\n }\n }\n ]\n }\n },\n {\n \"questions\": {\n \"title\": \"Prevention\",\n \"description\": \"The following questions focus on preventing future incidents from occurring.\",\n \"questions\": [\n {\n \"id\": \"IP1\",\n \"title\": \"Problem investigation - 5 Whys\",\n \"description\": \"Start with the initial problem of the incident and ask why until all root causes and contributing factors are listed. When listing root causes consider environmental and systemic factors that may have contributed prior to the incident. Consider taking action items against all contributing causes if appropriate.\",\n \"answer\": {\n \"multi\": {\n \"addButtonText\": \"Add problem\",\n \"definition\": {\n \"composite\": {\n \"definitions\": [\n {\n \"description\": \"Problem definition - define the problem\",\n \"text\": {\n }\n },\n {\n \"optional\": true,\n \"description\": \"Why did this problem occur?\",\n \"indent\": 1,\n \"multi\": {\n \"initialSize\": 5,\n \"addButtonText\": \"Add why\",\n \"definition\": {\n \"pair\": {\n \"left\": {\n \"description\": \"Why?\",\n \"text\": {\n }\n },\n \"right\": {\n \"description\": \"Lessons learned\",\n \"text\": {\n }\n }\n }\n }\n }\n }\n ]\n }\n }\n }\n }\n },\n {\n \"id\": \"IP2\",\n \"title\": \"Additional lessons learned\",\n \"description\": \"What additional lessons can be learned from this incident or analysis to prevent ore reduce impact of future incidents?\",\n \"optional\": true,\n \"answer\": {\n \"multi\": {\n \"definition\": {\n \"description\": \"Lessons learned\",\n \"text\": {\n }\n }\n }\n }\n }\n ]\n }\n }\n ]\n },\n {\n \"id\": \"related\",\n \"name\": \"Related items\",\n \"components\": [\n {\n \"relatedItems\": {\n }\n }\n ]\n },\n {\n \"id\": \"actions\",\n \"name\": \"Action items\",\n \"components\": [\n {\n \"actions\": {\n }\n }\n ]\n }\n ]\n}\n",
"DocumentType": "ProblemAnalysisTemplate",
"DocumentFormat": "JSON"
}
Step2. 更新したファイルをアップロードする
Step2-1. アップロードするときの --name について。
下記のようなコマンドでアップロードしますが、--name の引数が、分析を行う際にテンプレートを呼び出すときの名前になります。
awscli
aws ssm create-document --name Customized-Incidents-PostIncidentAnalysis --document-type ProblemAnalysisTemplate --content file://customized.json
その名前が AWSIncidents-PostIncidentAnalysisTemplate_Customized とかだと怒られます。aws-, amazon, amzn が先頭に来るのはAWS側で予約されているから、ということらしいです。
エラー
[ec2-user@ip-172-31-1-202 ~]$ aws ssm create-document --name AWSIncidents-PostIncidentAnalysis_customized --document-type ProblemAnalysisTemplate --content file://customized.json
An error occurred (ValidationException) when calling the CreateDocument operation: Invalid document name AWSIncidents-PostIncidentAnalysis_customized
[ec2-user@ip-172-31-1-202 ~]$
Step2-2. 更新したファイルの指定の仕方がわからなかった。
--content の引数として更新したファイルを指定するわけですが、指定方法がわかりませんでした。
ちなみに、下記状況としては、カスタマイズしたファイルが ローカルディレクトリに customized.json として保存されている想定。
--content customized.json と指定してみた。ダメだった。
うまくいかず
[ec2-user@ip-172-31-1-202 ~]$ aws ssm create-document --name Customized-Incidents-PostIncidentAnalysis1 --document-type ProblemAnalysisTemplate --content customized.json
An error occurred (InvalidDocumentContent) when calling the CreateDocument operation: invalid document content JSON
[ec2-user@ip-172-31-1-202 ~]$
--content ./customized.json と指定してみた。ダメだった。
うまくいかず
[ec2-user@ip-172-31-1-202 ~]$ aws ssm create-document --name Customized-Incidents-PostIncidentAnalysis1 --document-type ProblemAnalysisTemplate --content ./customized.json
An error occurred (InvalidDocumentContent) when calling the CreateDocument operation: invalid document content JSON
[ec2-user@ip-172-31-1-202 ~]$
--content file://customized.json が正解だった。
Step2-3. アップロードするファイルの中身について
get-document でダウンロードしたファイルのカスタマイズしたい箇所だけ変更して create-document すればいいのかとおもったのだが、以下のエラーとなった。意味がよくわからん。
JSONで落としてきて、確かに中身はJSONで、そのまま必要なとこだけ更新してアップロードすれば、問題なさそうなのに。
エラー
[ec2-user@ip-172-31-1-202 ~]$ aws ssm create-document --name Customized-Incidents-PostIncidentAnalysis7 --document-type ProblemAnalysisTemplate --content file://customized.json
An error occurred (InvalidDocumentContent) when calling the CreateDocument operation: #: required key [sections] not found#: extraneous key [Status] is not permitted#: extraneous key [DocumentFormat] is not permitted#: extraneous key [Content] is not permitted#: extraneous key [CreatedDate] is not permitted#: extraneous key [DocumentType] is not permitted#: extraneous key [DocumentVersion] is not permitted#: extraneous key [Name] is not permitted#: 8 schema violations found
[ec2-user@ip-172-31-1-202 ~]$
結論から言うと、ダウンロードしたJSONファイルの中の Content の中身だけを抜きだして、アップロードしないとだめでした。
まぁ、よくよく考えると、その他の行の[Name]とか[Document type]とかは creat-document コマンドの引数としても指定してるしね。
かつ、Content の中身は、以下の様に、改行が【¥n】と表現されていたり【\】が余分についていたりだったので。
1．\n を 改行に置換。
2．\ を 削除 (\" を " に置換しました)
の2つを実施し、以下のような Content の中を json 形式にしたファイルを作成しアップロードします。
※ファイルが長いですが、最初と最後の{}あたりがわかるように全部そのまま乗っけます。
json
{
"sections": [
{
"id": "overview",
"name": "Overview",
"components": [
{
"questions": {
"title": "Summary",
"description": "日本語テスト：Provide a summary of the incident, include the following; what happened, why it happened, how it was mitigated, and what is being done about it at a high level.",
"questions": [
{
"id": "S1",
"answer": {
"markdown": {
}
}
}
]
}
},
{
"questions": {
"title": "Impact",
"description": "A 1-2 paragraph summary of the customer-facing impact (or experience) during the event. Do not mention customers by name in this section. Provide explicit figures to detail the blast radius.",
"questions": [
{
"id": "I1",
"answer": {
"markdown": {
}
}
}
]
}
}
]
},
{
"id": "metrics",
"name": "Metrics",
"components": [
{
"metrics": {
"title": "Metrics",
"description": "Metrics with detailed information about impact. When available, metrics from related incidents are imported and displayed here."
}
}
]
},
{
"id": "timeline",
"name": "Timeline",
"components": [
{
"timeline": {
}
}
]
},
{
"id": "questions",
"name": "Incident questions",
"components": [
{
"questions": {
"title": "Detection",
"description": "The following questions help guide your team to detect incidents more effectively.",
"questions": [
{
"id": "ID1",
"title": "How could time to detection be improved? As a thought exercise, how would you cut the time in half?",
"answer": {
"text": {
}
}
},
{
"id": "ID2",
"title": "What adjustments could be made to the metrics used for detection?",
"answer": {
"pair": {
"left": {
"description": "Adjustments",
"multiSelect": {
"items": [
{
"value": "Add metric",
"recommendation": {
"id": "amzn-add-metric",
"title": "Add detection metric",
"description": "Create or update a CloudWatch metric",
"size": "MEDIUM",
"priority": "HIGH"
}
},
{
"value": "Update resolution",
"recommendation": {
"id": "amzn-update-resolution",
"title": "Update detection metric resolution",
"description": "Create or update a CloudWatch metric",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Improve quality of data",
"recommendation": {
"id": "amzn-improve-quality-of-data",
"title": "Improve the quality of detection metric data",
"description": "Create or update a CloudWatch metric",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Other"
},
{
"value": "No actions needed"
}
]
}
},
"right": {
"description": "Comments",
"optional": true,
"text": {
}
}
}
}
},
{
"id": "ID3",
"title": "What adjustments could be made to the alarms used for detection?",
"answer": {
"pair": {
"left": {
"description": "Adjustments",
"multiSelect": {
"items": [
{
"value": "Add alarm",
"recommendation": {
"id": "amzn-add-alarm",
"title": "Add detection alarm",
"description": "Create or update a CloudWatch alarm",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Update threshold",
"recommendation": {
"id": "amzn-update-threshold",
"title": "Update detection alarm theshold",
"description": "Create or update a CloudWatch alarm",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Update severity",
"recommendation": {
"id": "amzn-update-severity",
"title": "Update detection alarm severity",
"description": "Create or update a CloudWatch alarm",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Other"
},
{
"value": "No adjustments needed"
}
]
}
},
"right": {
"description": "Comments",
"optional": true,
"text": {
}
}
}
}
}
]
}
},
{
"questions": {
"title": "Diagnosis",
"description": "The following questions help guide your team to triage incidents more effectively.",
"questions": [
{
"id": "DN1",
"title": "How could time to diagnosis be improved? As a thought exercise, how would you cut the time in half?",
"answer": {
"text": {
}
}
},
{
"id": "DN2",
"title": "Do any of the following need to be updated to engage the correct contact faster?",
"answer": {
"pair": {
"left": {
"description": "Resource",
"multiSelect": {
"items": [
{
"value": "Escalation plan",
"recommendation": {
"id": "amzn-update-escalation-plan",
"title": "Update escalation plan",
"description": "Create or update escalation plan",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Steps in response plan",
"recommendation": {
"id": "amzn-update-response-plan",
"title": "Update response plan",
"description": "Create or update response plan",
"size": "SMALL",
"priority": "HIGH"
}
},
{
"value": "Other"
},
{
"value": "No updates needed"
}
]
}
},
"right": {
"description": "Comments",
"optional": true,
"text": {
}
}
}
}
}
]
}
},
{
"questions": {
"title": "Mitigation",
"description": "The following questions investigate ways to decrease MTTR.",
"questions": [
{
"id": "MT1",
"title": "How could time to mitigation be improved? As a thought exercise, how would you cut the time in half?",
"answer": {
"text": {
}
}
},
{
"id": "MT2",
"title": "Could the runbook for the incident be improved? Did the runbook contain unnecessary steps or lack ones that would help?",
"answer": {
"pair": {
"left": {
"singleSelect": {
"items": [
{
"value": "N/A"
},
{
"value": "No"
},
{
"value": "Yes",
"recommendation": {
"id": "amzn-update-runbook",
"title": "Update incident runbook",
"description": "Create or update runbook",
"priority": "HIGH",
"size": "SMALL"
}
}
]
}
},
"right": {
"description": "Comments",
"optional": true,
"text": {
}
}
}
}
}
]
}
},
{
"questions": {
"title": "Prevention",
"description": "The following questions focus on preventing future incidents from occurring.",
"questions": [
{
"id": "IP1",
"title": "Problem investigation - 5 Whys",
"description": "Start with the initial problem of the incident and ask why until all root causes and contributing factors are listed. When listing root causes consider environmental and systemic factors that may have contributed prior to the incident. Consider taking action items against all contributing causes if appropriate.",
"answer": {
"multi": {
"addButtonText": "Add problem",
"definition": {
"composite": {
"definitions": [
{
"description": "Problem definition - define the problem",
"text": {
}
},
{
"optional": true,
"description": "Why did this problem occur?",
"indent": 1,
"multi": {
"initialSize": 5,
"addButtonText": "Add why",
"definition": {
"pair": {
"left": {
"description": "Why?",
"text": {
}
},
"right": {
"description": "Lessons learned",
"text": {
}
}
}
}
}
}
]
}
}
}
}
},
{
"id": "IP2",
"title": "Additional lessons learned",
"description": "What additional lessons can be learned from this incident or analysis to prevent ore reduce impact of future incidents?",
"optional": true,
"answer": {
"multi": {
"definition": {
"description": "Lessons learned",
"text": {
}
}
}
}
}
]
}
}
]
},
{
"id": "related",
"name": "Related items",
"components": [
{
"relatedItems": {
}
}
]
},
{
"id": "actions",
"name": "Action items",
"components": [
{
"actions": {
}
}
]
}
]
}
やっとうまくアップロード出来ました。
awscli
[ec2-user@ip-172-31-1-202 ~]$ aws ssm create-document --name Customized-Incidents-PostIncidentAnalysis1 --document-type ProblemAnalysisTemplate --content file://customized.json
{
"DocumentDescription": {
"Hash": "a9b47c3d97db941e9e21ba04a74528222fee0121346cf907",
"HashType": "Sha256",
"Name": "Customized-Incidents-PostIncidentAnalysis1",
"Owner": "914432xxxxx",
"CreatedDate": "2021-06-04T11:42:07.886000+00:00",
"Status": "Creating",
"DocumentVersion": "1",
"PlatformTypes": [],
"DocumentType": "ProblemAnalysisTemplate",
"SchemaVersion": "",
"LatestVersion": "1",
"DefaultVersion": "1",
"DocumentFormat": "JSON",
"Tags": []
}
}
[ec2-user@ip-172-31-1-202 ~]$