Bekerja dengan dokumen

Bagian ini mencakup informasi tentang cara menggunakan dan bekerja dengan dokumen SSM.

Daftar Isi

• Menggunakan dokumen SSM dalam Asosiasi State Manager
• Membandingkan versi dokumen SSM
• Membuat dokumen SSM (konsol)
• Membuat dokumen SSM (baris perintah)
• Membuat dokumen SSM (API)
• Menghapus dokumen SSM khusus
• Menjalankan dokumen dari lokasi terpencil
• Membagikan dokumen SSM
• Mencari dokumen SSM

Menggunakan dokumen SSM dalam Asosiasi State Manager

Jika Anda membuat dokumen SSM untukState Manager, kemampuan AWS Systems Manager, Anda harus mengaitkan dokumen dengan instance terkelola setelah Anda menambahkan dokumen ke sistem. Untuk informasi selengkapnya, lihat Bekerja dengan asosiasi di Systems Manager.

Ingatlah detail berikut saat menggunakan dokumen SSM dalam State Manager asosiasi.

• Anda dapat menetapkan beberapa dokumen ke target dengan membuat State Manager asosiasi berbeda yang menggunakan dokumen berbeda.

• Jika Anda membuat dokumen dengan plugin yang bertentangan (misalnya, domain bergabung dan menghapus dari domain), plugin terakhir yang dijalankan akan menjadi status akhir. State Managertidak memvalidasi urutan logis atau rasionalitas perintah atau plugin dalam dokumen Anda.

• Ketika memproses dokumen, asosiasi instans diterapkan pertama kali, dan asosiasi grup yang ditandai diterapkan berikutnya. Jika instans adalah bagian dari beberapa kelompok yang ditandai, maka dokumen yang merupakan bagian dari kelompok yang ditandai tidak akan dijalankan dalam urutan tertentu. Jika instans langsung ditargetkan melalui beberapa dokumen dengan ID instans nya, tidak ada urutan tertentu pada eksekusi.

• Jika Anda mengubah versi default dokumen Kebijakan SSM untukState Manager, asosiasi apa pun yang menggunakan dokumen akan mulai menggunakan versi default baru saat Systems Manager menerapkan asosiasi ke instance berikutnya.

• Jika Anda membuat asosiasi menggunakan dokumen SSM yang dibagikan dengan Anda, dan kemudian pemilik berhenti membagikan dokumen dengan Anda, asosiasi Anda tidak lagi memiliki akses ke dokumen tersebut. Namun, jika pemilik membagikan dokumen SSM yang sama dengan Anda lagi nanti, asosiasi Anda secara otomatis memetakan ulang dokumen tersebut.

Membandingkan versi dokumen SSM

Anda dapat membandingkan perbedaan konten antar versi dokumen AWS Systems Manager (SSM) di konsol Systems Manager Documents. Ketika membandingkan versi dokumen SSM, perbedaan antara konten dari versi yang disorot.

Untuk membandingkan konten dokumen SSM (konsol)

1. Buka AWS Systems Manager konsol di https://console.aws.amazon.com/systems-manager/.

2. Di panel navigasi, pilih Dokumen.

3. Dalam daftar dokumen, pilih dokumen yang kontennya ingin Anda bandingkan.

4. Pada tab Konten, pilih Bandingkan versi, dan pilih versi dokumen yang ingin Anda bandingkan kontennya.

Membuat dokumen SSM (konsol)

Setelah Anda membuat konten untuk dokumen SSM kustom Anda, seperti yang dijelaskan dalam Menulis konten dokumen SSM, Anda dapat menggunakan konsol Systems Manager untuk membuat dokumen SSM menggunakan konten Anda.

Untuk membuat dokumen SSM (konsol)

1. Buka AWS Systems Manager konsol di https://console.aws.amazon.com/systems-manager/.

2. Di panel navigasi, pilih Dokumen.

3. Pilih Buat perintah atau sesi.

4. Masukkan nama deskriptif untuk dokumen

5. (Opsional) Untuk Jenis target, tentukan jenis sumber daya dokumen yang dapat dijalankan.

6. Di daftar Jenis dokumen, pilih jenis dokumen yang ingin Anda buat.

7. Hapus tanda kurung di bidang Konten, dan kemudian paste dokumen konten yang Anda buat sebelumnya.

8. (Opsional) Dalam bagian Tag dokumen, terapkan satu pasangan nilai kunci tag atau lebih ke dokumen.

   Tag adalah metadata opsional yang Anda tetapkan ke sumber daya. Tag memungkinkan Anda untuk mengkategorikan sumber daya dengan berbagai cara, seperti berdasarkan tujuan, pemilik, atau lingkungan. Misalnya, Anda mungkin ingin menandai dokumen untuk mengidentifikasi jenis tugas yang dijalankannya, jenis sistem operasi target, dan lingkungan tempat ia berjalan. Dalam kasus ini, Anda bisa menentukan pasangan nama/nilai kunci berikut:

   • Key=TaskType,Value=MyConfigurationUpdate

   • Key=OS,Value=AMAZON_LINUX_2

   • Key=Environment,Value=Production

   Untuk informasi selengkapnya tentang penandaan sumber daya Systems Manager, lihat Penandaan sumber daya Systems Manager.

9. Pilih Buat dokumen untuk menyimpan dokumen.

Membuat dokumen SSM (baris perintah)

Setelah Anda membuat konten untuk dokumen kustom AWS Systems Manager (SSM) Anda, seperti yang dijelaskan dalamMenulis konten dokumen SSM, Anda dapat menggunakan AWS Command Line Interface (AWS CLI) atau AWS Tools for PowerShell untuk membuat dokumen SSM menggunakan konten Anda. Hal ini ditunjukkan dalam perintah berikut.

Sebelum Anda mulai

Instal dan konfigurasikan AWS CLI atau AWS Tools for PowerShell, jika Anda belum melakukannya. Untuk selengkapnya, lihat Menginstal atau memperbarui versi terbaru AWS CLI dan Menginstal AWS Tools for PowerShell.

Jalankan perintah berikut. Ganti setiap placeholder sumber daya contoh dengan informasi Anda sendiri.

Linux & macOS

aws ssm create-document \
--content file://path/to/file/documentContent.json \
--name "document-name" \
--document-type "Command" \
--tags "Key=tag-key,Value=tag-value"

Windows

aws ssm create-document ^
--content file://C:\path\to\file\documentContent.json ^
--name "document-name" ^
--document-type "Command" ^
--tags "Key=tag-key,Value=tag-value"

PowerShell

$json = Get-Content -Path "C:\path\to\file\documentContent.json" | Out-String
New-SSMDocument `
-Content $json `
-Name "document-name" `
-DocumentType "Command" `
-Tags "Key=tag-key,Value=tag-value"

Jika berhasil, sistem menampilkan respon seperti berikut ini.

{
"DocumentDescription":{
  "CreatedDate":1.585061751738E9,
  "DefaultVersion":"1",
  "Description":"MyCustomDocument",
  "DocumentFormat":"JSON",
  "DocumentType":"Command",
  "DocumentVersion":"1",
  "Hash":"0d3d879b3ca072e03c12638d0255ebd004d2c65bd318f8354fcde820dEXAMPLE",
  "HashType":"Sha256",
  "LatestVersion":"1",
  "Name":"Example",
  "Owner":"111122223333",
  "Parameters":[
     --truncated--
  ],
  "PlatformTypes":[
     "Windows",
     "Linux"
  ],
  "SchemaVersion":"0.3",
  "Status":"Creating",
  "Tags": [
        {
            "Key": "Purpose",
            "Value": "Test"
        }
    ]
}
}

Membuat dokumen SSM (API)

Setelah membuat konten untuk dokumen kustom AWS Systems Manager (SSM), seperti yang dijelaskan dalamMenulis konten dokumen SSM, Anda dapat menggunakan SDK pilihan Anda untuk memanggil operasi AWS Systems Manager CreateDocumentAPI guna membuat dokumen SSM menggunakan konten Anda. String JSON atau YAML untuk permintaan parameter Content umumnya dibaca dari sebuah file. Contoh berikut adalah fungsi membuat dokumen SSM menggunakan SDK untuk Python, Go, dan Java.

Python

import boto3

ssm = boto3.client('ssm')
filepath = '/path/to/file/documentContent.yaml'

def createDocumentApiExample():
with open(filepath) as openFile:
    documentContent = openFile.read()
    createDocRequest = ssm.create_document(
        Content = documentContent,
        Name = 'createDocumentApiExample',
        DocumentType = 'Automation',
        DocumentFormat = 'YAML' 
    )
    print(createDocRequest)

createDocumentApiExample()

Go

package main

import (
"github.com/aws/aws-sdk-go/aws"
"github.com/aws/aws-sdk-go/aws/session"
"github.com/aws/aws-sdk-go/service/ssm"

"fmt"
"io/ioutil"
"log"
)


func main() {
openFile, err := ioutil.ReadFile("/path/to/file/documentContent.yaml")
if err != nil {
    log.Fatal(err)
}
documentContent := string(openFile)
sesh := session.Must(session.NewSessionWithOptions(session.Options{
    SharedConfigState: session.SharedConfigEnable}))

ssmClient := ssm.New(sesh)
createDocRequest, err := ssmClient.CreateDocument(&ssm.CreateDocumentInput{
    Content: &documentContent,
    Name:  aws.String("createDocumentApiExample"),
    DocumentType: aws.String("Automation"),
    DocumentFormat: aws.String("YAML"),
})
result := *createDocRequest
fmt.Println(result)
}

Java

import java.io.IOException;
import java.nio.charset.Charset;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Paths;

import com.amazonaws.AmazonClientException;
import com.amazonaws.AmazonServiceException;
import com.amazonaws.auth.AWSCredentials;
import com.amazonaws.auth.profile.ProfileCredentialsProvider;
import com.amazonaws.regions.Regions;
import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagement;
import com.amazonaws.services.simplesystemsmanagement.AWSSimpleSystemsManagementClientBuilder;
import com.amazonaws.services.simplesystemsmanagement.model.*;

public class createDocumentApiExample {
public static void main(String[] args) {
try {
  createDocumentMethod(getDocumentContent());
}
catch (IOException e) {
  e.printStackTrace();
}
}
public static String getDocumentContent() throws IOException {
  String filepath = new String("/path/to/file/documentContent.yaml");
    byte[] encoded = Files.readAllBytes(Paths.get(filepath));
    String documentContent = new String(encoded, StandardCharsets.UTF_8);
    return documentContent;
}

public static void createDocumentMethod (final String documentContent) {
  AWSSimpleSystemsManagement ssm = AWSSimpleSystemsManagementClientBuilder.defaultClient();
  final CreateDocumentRequest createDocRequest = new CreateDocumentRequest()
    .withContent(documentContent)
    .withName("createDocumentApiExample")
    .withDocumentType("Automation")
    .withDocumentFormat("YAML");
  final CreateDocumentResult result = ssm.createDocument(createDocRequest);
}
}

Untuk informasi selengkapnya tentang membuat konten dokumen kustom, lihat Elemen dan parameter data.

Menghapus dokumen SSM khusus

Jika Anda tidak lagi ingin menggunakan dokumen SSM khusus, Anda dapat menghapusnya dengan menggunakan AWS Command Line Interface (AWS CLI) atau AWS Systems Manager konsol.

Untuk menghapus dokumen SSM ()AWS CLI

1. Sebelum Anda menghapus dokumen, kami sarankan Anda memisahkan semua instance yang terkait dengan dokumen.

   Jalankan perintah berikut untuk memisahkan instance dari dokumen.

   aws ssm delete-association --instance-id "123456789012" --name "documentName"

   Tidak ada output jika perintah berhasil.

2. Jalankan perintah berikut. Ganti setiap placeholder sumber daya contoh dengan informasi Anda sendiri.

   Linux

   aws ssm delete-document \
       --name "document-name" \
       --document-version "document-version" \
       --version-name "version-name"

   Windows

   aws ssm delete-document ^
       --name "document-name" ^
       --document-version "document-version" ^
       --version-name "version-name"

   PowerShell

   Delete-SSMDocument `
       -Name "document-name" `
       -DocumentVersion 'document-version' `
       -VersionName 'version-name'

   Tidak ada output jika perintah berhasil.

   penting

   Jika document-version atau tidak version-name disediakan, semua versi dokumen dihapus.

Untuk menghapus dokumen SSM (konsol)

1. Buka AWS Systems Manager konsol di https://console.aws.amazon.com/systems-manager/.

2. Di panel navigasi, pilih Dokumen.

3. Pilih dokumen yang ingin Anda hapus.

4. Pilih Hapus. Saat diminta untuk menghapus dokumen, pilih Hapus.