새로운 Terraform 버전으로 업그레이드하기

Schematics 에서 사용하는 오픈 소스 IaC 도구는 Terraform 및 Helm 의 새 버전과 이를 지원하는 Terraform 프로바이더와 함께 지속적으로 발전하고 있습니다. 오래 지속되는 작업공간 환경은 이전 버전이 더 이상 사용되지 않고 지원되지 않으므로 최신 버전의 Terraform을 활용하도록 업그레이드해야 합니다.

모든 Schematics 사용자는 조작 및 지원의 연속성을 보장하기 위해 정기적으로 최신 Terraform 버전으로 업그레이드하도록 권장합니다. Schematics 는 Terraform 릴리스에 대한 Hashicorp 지원 모델을 따르며 Hashicorp가 있는 라인에서 버전을 더 이상 사용하지 않습니다.

Terraform v1.0 은 Terraform의 주요 릴리스이며 안정된 1.x 릴리스로 상태 전이를 표시합니다. Hashicorp는 1.x 릴리스에 대한 호환성 약속 을 했습니다. 핵심 기능의 경우 1.x 릴리스를 통해 업그레이드하는 데 추가 변경사항이 필요하지 않습니다.

즉, v1.x 릴리스 간의 업그레이드를 간단하게 수행하는 것이 목적이며, 구성을 변경할 필요가 없고, 업그레이드 단계를 실행할 명령이 없으며, Terraform에서 설정한 자동화를 변경할 필요가 없습니다.

1.x 릴리스로 업그레이드하려면 특정 Schematics 작업공간 조치가 필요하지 않습니다. TF 구성/템플리트 업데이트가 필요할 수 있는 릴리스 특정 변경사항은 Terraform 업그레이드 안내서 를 검토하십시오.

Terraform 템플리트 버전 1.x 이상 업그레이드

Terraform 1.0부터 Schematics 작업공간은 작업공간 버전에 대한 단순 변경을 통해 최신 1.x 릴리스로 업데이트할 수 있습니다. 0.x 릴리스에서 업데이트하려면 Terraform 템플리트 버전 0.x업그레이드 절을 참조하십시오.

Schematics 는 Terraform_v1.x 및 GA (General Availability) 후 릴리스를 사용 가능하게 할 계획 45-60 days 을 지원합니다. Terraform 템플리트는 보조 및 패치 릴리스에 대한 업그레이드를 허용하는 Terraform 템플리트의 versions.tf 에 있는 required_version 매개변수에 대해 >, >= 또는 ~> 와 같은 버전 범위 제한조건을 사용하는 것이 좋습니다. 이를 통해 Schematics 가 작업공간 버전에서 설정한 대로 Terraform 버전의 최신 패치 또는 부 릴리스를 자동으로 채택할 수 있습니다.

terraform {
required_version = "~> 1.1"
}

작업공간 Terraform 1.x 버전 업데이트

작업공간에 사용 중인 Terraform 버전은 Schematics 작업공간 업데이트 API를 통해 업데이트할 수 있습니다.

작업공간 terraform 버전 매개변수의 양식은 terraform_v1.4 또는 terraform_v1.5 입니다.

  1. 업데이트할 작업공간을 선택하고 Normal 상태에 있으며 계획 조작이 제안된 자원 변경사항을 생성하지 않는지 확인하십시오. workspace_id 를 저장하고 작업공간이 호스팅되는 지역을 기록하십시오.

  2. IBM Cloud CLI및 API를 사용하여 작업공간 terraform 버전을 업데이트하십시오. 이러한 작업공간 조작은 지역에 따라 다릅니다. 다음 명령에 필요하므로 UI의 작업공간 영역을 참고하십시오.

    • ibmcloud login 를 사용하여 IBM Cloud CLI에 로그인하십시오.
    • ibmcloud target -r <region> 가 있는 CLI 대상 리젼을 업데이트 중인 작업공간과 동일하게 설정하십시오.
    • ibmcloud iam oauth-tokens 명령을 사용하여 Schematics API와 함께 사용할 IAM oauth 토큰을 생성하십시오.
    • 토큰 데이터를 복사하고 다음 명령 텍스트에 삽입하여 <token-data> 문자열을 대체하고 <terraform_version> 를 필수 Terraform 버전 및 <workspace_id> 로 설정하십시오.
    • 작업공간은 Terraform 버전을 업데이트하기 위해 cURL 명령을 실행하여 Schematics 업데이트 API를 호출하여 업데이트됩니다. 이 오퍼레이션은 지역에 따라 다르며 작업공간 대상 지역에 대해 원하는 Schematics API 지역 엔드포인트 를 지정해야 합니다. 명령의 <schematics-region-endpoint> 텍스트를 대상 작업공간 리젼의 엔드포인트로 바꾸십시오.
        curl -X PUT https://<schematics-region-endpoint>.cloud.ibm.com/v1/workspaces/<w_id> \
    -H 'Authorization: Bearer <token>' \
    -H 'refresh_token: <token>' \
    -d '{
    "type": [
        "<terraform_version>"
    ],
    "template_data": [
        {
            "folder": ".",
            "type": "<terraform_version>"
        }
    ]
    }'

  3. 작업공간 설정 페이지에서 TF 버전이 이제 원하는 버전으로 설정되었는지 확인하십시오.

  4. 작업공간에 대해 계획 생성 오퍼레이션을 실행하십시오. 명령이 오류 없이 성공적으로 실행되고 예기치 않은 메시지가 로그되지 않는지 유효성 검증하십시오. 계획으로 인해 자원에 대해 제안된 변경사항이 없어야 합니다.

  5. 작업공간에 대해 계획 적용 조작을 실행하십시오. 명령이 오류 없이 성공적으로 실행되고 예기치 않은 메시지가 로그되지 않는지 유효성 검증하십시오.

  6. 이제 업그레이드가 완료되었습니다.

Terraform 템플리트 버전 0.x 를 1.x 로 업그레이드

0.x 릴리스에서 Terraform 버전 업그레이드는 각 릴리스를 통해 업그레이드하는 단계별 프로세스입니다. 업그레이드는 여러 릴리스에서의 업그레이드를 지원하지 않으므로 릴리스별로 수행해야 합니다. 일부 업데이트에서는 Terraform upgrade 명령을 실행하여 구성 파일을 수정해야 하고 Terraform 상태 파일도 변경됩니다. 이러한 단계는 Schematics내에서 수행할 수 없습니다. 작업공간 Terraform 템플리트는 Terraform의 로컬 사본을 사용하여 업그레이드해야 합니다. 0.x 릴리스를 업그레이드하기 위한 단계를 따르십시오.

Terraform 버전 목록
버전 권장사항
v0.12 v0.13 업그레이드 안내서 를 검토하고 Terraform v0.12 작업공간을 v0.13 으로 업그레이드 Schematics 는 더 이상 사용되지 않음 Terraform v0.12 지시사항을 따르십시오.
v0.13 Terraform v0.14 업그레이드의 경우 상태 형식 업그레이드를 완료하려면 Terraform v0.14 와 함께 terraform apply 를 실행해야 합니다. 오류가 발생하면 v0.14 업그레이드 안내서를 참조하십시오. upgrade-13-to10 지시사항을 따르십시오.
v0.14 Terraform v1.0 버전으로 직접 업그레이드할 수 있습니다. v0.15 업그레이드 안내서를 검토하십시오.
v0.15 Terraform v1.0 버전으로 직접 업그레이드할 수 있습니다. v1.0 업그레이드 안내서를 검토하십시오.

Terraform v0.12 작업공간을 v0.13 으로 업그레이드

Terraform의 v0.13 버전을 사용하도록 v0.12 작업공간을 업그레이드하는 것은 다단계 태스크입니다. 관련 버전 업그레이드에 대해 Terraform 업그레이드 안내서 를 주의깊게 검토해야 합니다.

Schematics 작업 공간에서 최신 Terraform 버전으로 업그레이드하려면 다음 단계를 따르세요.

  1. 최신 구문 및 시맨틱을 사용하도록 Terraform 구성 파일을 업그레이드하십시오.

  2. Terraform 상태 파일을 최신 버전과 호환되도록 마이그레이션하십시오. Schematics 는 Terraform 상태 파일에 대한 내장 수정 기능을 지원하지 않습니다. 따라서 이러한 단계를 수행해야 합니다.

    1. 로컬 시스템에서 Terraform 구성 파일 및 Terraform 상태 파일의 업그레이드된 버전을 준비하십시오.
    2. 새 Terraform 구성 파일 및 Terraform 상태 파일을 사용하여 새 Schematics 작업공간 을 작성하십시오.
    3. 리소스를 영구 삭제하지 않고 이전 작업공간을 삭제하십시오.

다음은 0.12 에서 0.13: 으로 업그레이드하기 위한 자세한 단계입니다.

  1. v0.12 의 Schematics 작업공간에 자원이 있는지, 마지막 적용에 성공했는지, 작업공간이 normal 상태인지 확인하십시오. Terraform v0.12 를 위해 Terraform 구성 파일과 Terraform 상태 파일이 일관된 상태인지 확인하십시오.
  2. Terraform v0.12 Schematics 작업 공간에서 사용되는 Git 저장소를 로컬 컴퓨터에 다운로드하거나 클론하십시오.
  3. 로컬 시스템에 Terraform 0.13 을 설치하십시오.
  4. 클론한 저장소의 디렉터리로 이동한 후, Terraform v0.13upgrade 명령어를 실행하여 구성 파일을 Terraform v0.13 버전으로 업데이트하십시오. 자세한 내용은 ‘ Terraform v0.13 로 업그레이드하기’ 문서를 참조하십시오. 업그레이드 명령은 terraform 구성 블록이 있는 versions.tf 파일을 생성합니다.
  5. 코드 블록에 표시된 대로 versions.tf 파일을 편집하여 소스 매개변수를 source = "IBM-Cloud/ibm" 로 설정하십시오.

versions.tf 파일

```terraform {: codeblock}
terraform {
    required_providers {
    ibm = {
      # TF-UPGRADE-TODO
      #
      # No source detected for this provider. You must add a source address
      # in the following format:
      #
      source = "IBM-Cloud/ibm"
      #
      # For more information, see the provider source documentation:
      #
    }
    }
    required_version = ">= 0.13"
}
```

  1. Schematics state pull 명령을 사용하여 기존 Schematics 작업공간에서 Terraform 상태 파일을 다운로드하십시오.

    tfstate 를 사용하여 작업 공간이 생성되면, Schematics 은 이를 보안 파일로 간주합니다. 또한, 생성된 tfstate 파일을 UI를 통해 불러올 수 없습니다. 명령행을 사용하여 상태 파일을 가져오고 작업공간을 작성 해야 합니다.

    다운로드된 상태 파일을 terraform.tfstate 로 Terraform 실행 폴더에 복사하십시오.

  2. 명령행에서 상태 대체 제공자 명령을 실행하여 상태 파일에서 IBM Cloud 제공자 버전을 업데이트하십시오.

    terraform state replace-provider registry.terraform.io/-/ibm registry.terraform.io/ibm-cloud/ibm.

  3. Terraform 버전이 1.3 에서 >= 1.4 로 업데이트되고 제공자가 registry.terraform.io/ibm-cloud/ibm 로 업데이트되는 terraform.tfstate 파일이 업데이트되었는지 확인하십시오.

  4. 업그레이드된 TF 구성 파일 및 version.tf 을 다시 Git 저장소로 푸시하십시오.

  5. 수정된 terraform.tfstate 파일의 컨텐츠를 state.json 파일에 복사하십시오.

  6. 코드 블록에 표시된 대로 workspace.json 파일을 작성하거나 업데이트하십시오.

    {
    "name": "gb",
    "type": [
        "terraform_v1.4"
    ],
    "description": "migration workspace",
    "template_repo": {
        "url": "Provide your Git repository link"
    },
    "workspace_status" : {
        "frozen": false
    },
    "template_data": [{
        "folder": ".",
        "type": "terraform_v1.4"
    }]
}

  7. 명령줄에서 다음 명령을 실행하여 새 Terraform v0.13 워크스페이스를 만듭니다:

    • ibmcloud schematics workspace new --file workspace.json --state state.json.

    • ibmcloud schematics workspace get --id  <workspace-id>. 작업 공간 상태가 ‘ inactive ’가 아닌 경우, 몇 초간 기다린 후 명령을 다시 실행해 주세요.

    • ibmcloud schematics plan id <workspace id>.

    • ibmcloud schematics job get --id <job-id form plan>. 작업 공간 계획 상태가 ‘ success ’가 아닌 경우, 몇 초간 기다린 후 명령을 다시 실행해 보세요.

    • ibmcloud schematics apply --id <workspace id>.

    • ibmcloud schematics job get --id <job-id from apply>.

  8. [선택 사항으로], Terraform v0.12 을 사용하는 ‘ Schematics ’ 작업 공간을 삭제할 수 있습니다.

    이전 작업공간에서 사용하는 리소스를 영구 삭제하지 마십시오.

Terraform 템플리트를 v0.13 이상에서 v1.0 로 업그레이드

0.13 ~ 0.15 버전은 단계별 업그레이드가 필요합니다(0.13 to 0.14, 0.14 to 0.15, 0.15 to 1.0).

프로세스는 각 버전 단계에 대해 동일합니다. 각 버전이 변경된 후에는 Terraform Apply가 실행되어야 합니다. 이는 해당 버전 및 해당 버전에만 관련된 스키마 변경사항으로 Terraform 상태 파일을 업데이트합니다. 단일 버전을 업그레이드한 후 다음 버전 업데이트를 수행할 수 있습니다.

  1. 릴리스에 대한 Terraform 업그레이드 안내서 를 읽고 필요한 구성 변경사항을 구현하십시오.
  2. Terraform 템플리트 버전 1.x 이상 업그레이드 에 설명된 프로세스에 따라 단일 버전을 대상 버전으로 업그레이드하십시오.
  3. 작업공간 설정 페이지에서 TF 버전이 이제 원하는 버전으로 설정되었는지 확인하십시오.
  4. 작업공간에 대해 계획 생성 오퍼레이션을 실행하십시오. 명령이 오류 없이 성공적으로 실행되고 예기치 않은 메시지가 로그되지 않는지 유효성 검증하십시오. 계획으로 인해 자원에 대해 제안된 변경사항이 없어야 합니다.
  5. 작업공간에 대해 계획 적용 조작을 실행하십시오. 이 단계는 Terraform 상태 파일 업데이트를 수행하는 데 필수 입니다. 명령이 오류 없이 성공적으로 실행되고 예기치 않은 메시지가 로그되지 않는지 유효성 검증하십시오.
  6. 이제 단일 버전 단계를 업그레이드했습니다.