Adobe Experience Manager에 대한 OSGi를 Cloud Service으로 구성

OSG 는 AEM(Adobe Experience Manager)의 기술 스택에서 기본적인 요소입니다. AEM 및 해당 구성의 합성 번들을 제어하는 데 사용됩니다.

OSGi는 표준화된 프리미티브 값을 제공하므로, 애플리케이션이 작고 재사용 가능하며 공동 작업 구성 요소에서 작성할 수 있습니다. 이러한 구성 요소는 애플리케이션으로 구성하고 배포할 수 있습니다. 이를 통해 OSGi 번들을 중단, 설치 및 개별적으로 시작할 수 있으므로 간편하게 관리할 수 있습니다. 상호 종속성은 자동으로 처리됩니다. 각 OSGi 구성 요소는 다양한 번들 중 하나에 포함됩니다. 자세한 내용은 OSGi 사양을 참조하십시오.

AEM 코드 프로젝트의 일부인 구성 파일을 통해 OSGi 구성 요소에 대한 구성 설정을 관리할 수 있습니다.

OSGi 구성 파일

구성 변경 사항은 AEM 프로젝트의 코드 패키지(ui.apps)에서 런타임 모드 특정 구성 폴더 아래의 구성 파일(.cfg.json)로 정의됩니다.

/apps/example/config.<runmode>

OSGi 구성 파일의 형식은 Apache Sling 프로젝트에 의해 정의된 .cfg.json 형식을 사용하는 JSON 기반입니다.

OSGi 구성은 OSGi 구성 요소의 Java™ 클래스 이름으로 기본적으로 설정되어 있는 PID(Persistent Identity)를 통해 OSGi 구성 요소를 대상으로 합니다. 예를 들어, 다음을 통해 구현된 OSGi 서비스에 대한 OSGi 구성을 제공하려면 다음을 수행합니다.

com.example.workflow.impl.ApprovalWorkflow.java

OSGi 구성 파일은 다음 위치에 정의됩니다.

/apps/example/config/com.example.workflow.impl.ApprovalWorkflow.cfg.json

cfg.json OSGi 구성 형식을 따릅니다.

노트

이전 버전의 AEM에서는 .cfg, .config 및 XML sling:OsgiConfig 리소스 정의와 같은 다른 파일 형식을 사용하여 OSGi 구성 파일을 지원합니다. 이러한 형식은 cfg.json OSGi 구성 형식으로 대체됩니다.

실행 모드 해상도

특정 OSGi 구성은 런타임 모드를 사용하여 특정 AEM 인스턴스로 타깃팅할 수 있습니다. 실행 모드를 사용하려면 /apps/example(예: 프로젝트 이름) 아래에 구성 폴더를 다음 형식으로 만드십시오.

/apps/example/config.<author|publish>.<dev|stage|prod>/

이러한 폴더의 모든 OSGi 구성은 구성 폴더 이름에 정의된 런타임 모드가 AEM에서 사용하는 런타임 모드와 일치하는 경우에 사용됩니다.

예를 들어 AEM에서 런타임 모드 작성자 및 dev를 사용하는 경우 /apps/example/config.author//apps/example/config.author.dev/의 구성 노드가 적용되지만 /apps/example/config.publish//apps/example/config.author.stage/의 구성 노드는 적용되지 않습니다.

동일한 PID에 대해 여러 구성을 적용할 경우 일치하는 실행 모드가 가장 많은 구성이 적용됩니다.

이 규칙의 세부기간은 PID 수준입니다. 즉, 동일한 PID에 대해 /apps/example/config.author//apps/example/config.author.dev/의 보다 구체적인 속성을 정의할 수 없습니다. 일치하는 실행 모드 수가 가장 많은 구성은 전체 PID에 적용됩니다.

로컬에서 개발할 때 런타임 모드 시작 매개 변수를 전달하여 어떤 런타임 모드 OSGI 구성이 사용되는지를 지정할 수 있습니다.

OSGi 구성 값 유형

Cloud Service으로 Adobe Experience Manager에 사용할 수 있는 OSGi 구성 값에는 3가지 종류가 있습니다.

  1. 인라인 값. OSGi 구성에 하드 코딩되어 Git에 저장된 값입니다. 예:

    {
       "connection.timeout": 1000
    }
    
  2. 보안 값 - 보안상의 이유로 Git에 저장하지 않아야 하는 값입니다. 예:

    {
    "api-key": "$[secret:server-api-key]"
    } 
    
  3. 환경별 값 - 개발 환경에 따라 다른 값이므로 실행 모드로 정확하게 타깃팅할 수 없습니다(Cloud Service으로 Adobe Experience Manager에 단일 dev 실행 모드가 있으므로). 예:

    {
     "url": "$[env:server-url]"
    }
    

    단일 OSGi 구성 파일은 이러한 구성 값 유형의 조합을 함께 사용할 수 있습니다. 예:

    {
    "connection.timeout": 1000,
    "api-key": "$[secret:server-api-key]",
    "url": "$[env:server-url]"
    }
    

적절한 OSGi 구성 값 유형을 선택하는 방법

OSGi의 일반적인 경우 인라인 OSGi 구성 값을 사용합니다. 환경별 구성은 개발 환경 간에 값이 다른 특정 사용 사례에만 사용됩니다.

환경별 구성은 인라인 값을 포함하는 기존의 정적으로 정의된 OSGi 구성을 확장하여 Cloud Manager API를 통해 외부에서 OSGi 구성 값을 관리하는 기능을 제공합니다. 인라인 값을 정의하고 Git에 저장하는 일반적인 방식과 기존 방식을 사용해야 하는 시기와 환경별 구성으로 값을 추출하는 방법을 이해하는 것이 중요합니다.

다음 지침에서는 비보안 및 비밀 환경별 구성을 사용할 때 다룹니다.

인라인 구성 값 사용 시기

인라인 구성 값은 표준 방법으로 간주되며 가능한 경우 사용해야 합니다. 인라인 구성은 다음과 같은 이점을 제공합니다.

  • Git의 거버넌스 및 버전 내역을 통해 유지 관리됩니다
  • 값은 코드 배포에 암시적으로 연결되어 있습니다.
  • 추가 배포 고려 사항 또는 조정이 필요하지 않습니다.

OSGi 구성 값을 정의할 때마다 인라인 값으로 시작하고 사용 사례에 필요한 경우 비밀 또는 환경별 구성만 선택합니다.

비비밀 환경별 구성 값을 사용하는 경우

값이 개발 환경에 따라 다를 때 비보안 구성 값에 환경별 구성($[env:ENV_VAR_NAME])만 사용하십시오. 여기에는 로컬 개발 인스턴스와 Cloud Service 개발 환경으로 모든 Adobe Experience Manager이 포함됩니다. Cloud Service 단계 또는 프로덕션 환경에서 Adobe Experience Manager에 대해 비비밀 환경별 구성을 사용하지 마십시오.

  • 로컬 개발 인스턴스를 포함하여 개발 환경에 따라 다른 구성 값에 비비밀 환경별 구성만 사용하십시오.
  • 대신 스테이지 및 프로덕션 비비밀 값에 대해 OSGi 구성에서 표준 인라인 값을 사용합니다. 이와 관련하여, 런타임 시 스테이지 및 프로덕션 환경에 맞게 구성을 쉽게 변경할 수 있도록 환경별 구성을 사용하지 않는 것이 좋습니다.이러한 변경 사항은 소스 코드 관리를 통해 도입해야 합니다.

보안 환경별 구성 값 사용 시기

Adobe Experience Manager은 Cloud Service의 경우 암호, 개인 API 키 또는 보안상의 이유로 Git에 저장할 수 없는 기타 모든 보안 OSGi 구성 값에 환경별 구성($[secret:SECRET_VAR_NAME])을 사용해야 합니다.

보안 환경별 구성을 사용하여 스테이지 및 프로덕션 등 Cloud Service 환경에서 모든 Adobe Experience Manager에 기밀에 대한 가치를 저장할 수 있습니다.

OSGi 구성 만들기

아래에 설명된 것처럼 OSGi 구성을 만드는 방법에는 두 가지가 있습니다. 이전 방법은 일반적으로 개발자에 의한 잘 알려진 OSGi 속성과 값을 갖는 사용자 지정 OSGi 구성 요소 및 AEM 제공 OSGi 구성 요소에 대한 후자를 구성하는 데 사용됩니다.

OSGi 구성 작성 중

JSON 형식 OSGi 구성 파일은 AEM 프로젝트에서 직접 직접 작성할 수 있습니다. 널리 알려진 OSGi 구성 요소 및 구성을 정의하는 동일한 개발자에 의해 설계되고 개발된 맞춤형 OSGi 구성 요소에 대한 OSGi 구성을 만드는 가장 빠른 방법입니다. 이 방법을 사용하여 다양한 런타임 모드 폴더에 있는 동일한 OSGi 구성 요소에 대한 구성을 복사/붙여 넣고 업데이트할 수도 있습니다.

  1. IDE에서 ui.apps 프로젝트를 열고 새 OSGi 구성을 적용해야 하는 런타임 모드를 대상으로 하는 구성 폴더(/apps/.../config.<runmode>)를 찾거나 만듭니다
  2. 이 구성 폴더에서 새 <PID>.cfg.json 파일을 만듭니다. PID는 OSGi 구성 요소의 영구 ID입니다. 일반적으로 OSGi 구성 요소 구현의 전체 클래스 이름입니다. 예:
    /apps/.../config/com.example.workflow.impl.ApprovalWorkflow.cfg.json
    OSGi 구성 팩토리 파일 이름은 <PID>-<factory-name>.cfg.json 이름 지정 규칙을 사용합니다
  3. .cfg.json 파일을 열고 JSON OSGi 구성 형식에 따라 OSGi 속성 및 값 쌍의 키/값 조합을 정의합니다.
  4. 변경 내용을 새 .cfg.json 파일에 저장합니다.
  5. 새로운 OSGi 구성 파일을 Git에 추가 및 커밋

AEM SDK Quickstart을(를) 사용하여 OSGi 구성 생성

AEM SDK Quickstart Jar의 AEM 웹 콘솔을 사용하여 OSGi 구성 요소를 구성하고 OSGi 구성을 JSON으로 내보낼 수 있습니다. 이 기능은 AEM 프로젝트에서 OSGi 구성을 정의하는 개발자가 OSGi 속성 및 해당 값 형식을 제대로 이해하지 못할 수 있는 AEM 제공 OSGi 구성 요소를 구성하는 데 유용합니다.

노트

AEM 웹 콘솔의 구성 UI는 .cfg.json 파일을 저장소에 기록합니다. 따라서 AEM Project에서 정의한 OSGi 구성이 생성된 구성과 다를 수 있으므로 로컬 개발 중에 예상치 못한 잠재적인 동작을 방지하기 위해 이러한 사항을 주의하십시오.

  1. AEM SDK Quickstart Jar의 AEM 웹 콘솔에 관리 사용자로 로그인합니다
  2. OSGi > 구성으로 이동합니다.
  3. 구성하려면 OSGi 구성 요소를 찾고 제목을 눌러 편집합니다.
    OSGi 구성
  4. 필요에 따라 웹 UI를 통해 OSGi 구성 속성 값 편집
  5. PID(Persistent Id)를 안전한 위치에 기록합니다. 나중에 OSGi 구성 JSON을 생성하는 데 사용됩니다
  6. 저장을 탭합니다.
  7. OSGi > OSGi 설치 프로그램 구성 프린터로 이동합니다.
  8. 5단계에서 복사한 PID에 붙여넣기를 통해 일련화 형식이 "OSGi Configurator JSON"으로 설정되어 있는지 확인합니다.
  9. 인쇄 탭
  10. JSON 형식의 OSGi 구성은 직렬화된 구성 속성 섹션에 표시됩니다.
    OSGi 설치 프로그램 구성 프린터
  11. IDE에서 ui.apps 프로젝트를 열고 새 OSGi 구성을 적용해야 하는 런타임 모드를 대상으로 하는 구성 폴더(/apps/.../config.<runmode>)를 찾거나 만듭니다.
  12. 이 구성 폴더에서 새 <PID>.cfg.json 파일을 만듭니다. PID는 5단계의 값과 동일합니다.
  13. 10단계의 직렬화된 구성 속성을 .cfg.json 파일에 붙여 넣습니다.
  14. 변경 내용을 새 .cfg.json 파일에 저장합니다.
  15. 새로운 OSGi 구성 파일을 Git에 추가하고 커밋합니다.

OSGi 구성 속성 형식

인라인 값

인라인 값은 표준 JSON 구문에 따라 표준 이름-값 쌍으로 형식이 지정됩니다. 예:

{
   "my_var1": "val",
   "my_var2": [ "abc", "def" ],
   "my_var3": 500
}

환경별 구성 값

OSGi 구성은 환경에 따라 정의될 변수의 자리 표시자를 지정해야 합니다.

use $[env:ENV_VAR_NAME]

고객은 사용자 지정 코드와 관련된 OSGI 구성 속성에만 이 기술을 사용해야 합니다.Adobe 정의 OSGI 구성을 재정의하는 데 사용해서는 안 됩니다.

노트

자리 표시자는 repoinit 문에 사용할 수 없습니다.

비밀 구성 값

OSGi 구성은 환경에 따라 정의될 수 있는 보안에 대한 자리 표시자를 지정해야 합니다.

use $[secret:SECRET_VAR_NAME]

변수 이름 지정

다음은 환경별 및 비밀 구성 값 모두에 적용됩니다.

변수 이름은 다음 규칙을 따라야 합니다.

  • 최소 길이:2
  • 최대 길이:100년
  • regex와 일치해야 함:[a-zA-Z_][a-zA-Z_0-9]*

변수의 값은 2048자를 초과할 수 없습니다.

기본값

다음은 환경별 및 비밀 구성 값 모두에 적용됩니다.

환경 단위 값이 설정되지 않은 경우 런타임에 자리 표시자가 교체되지 않고 보간이 발생하지 않으므로 이 자리 표시자는 그대로 유지됩니다. 이를 방지하기 위해 다음 구문을 사용하여 자리 표시자의 일부로 기본값을 제공할 수 있습니다.

$[env:ENV_VAR_NAME;default=<value>]

기본값이 제공되면 자리 표시자는 환경 단위 값 또는 제공된 기본값으로 대체됩니다.

로컬 개발

다음은 환경별 및 비밀 구성 값 모두에 적용됩니다.

변수는 런타임 시 로컬 AEM에서 선택되도록 로컬 환경에서 정의할 수 있습니다. 예를 들어 Linux®에서:

export ENV_VAR_NAME=my_value

AEM을 시작하기 전에 구성에 사용된 환경 변수를 설정하고 이를 실행하는 간단한 배쉬 스크립트를 작성하는 것이 좋습니다. https://direnv.net/과 같은 도구를 사용하여 이 방법을 단순화합니다. 값 유형에 따라 모든 사람 간에 공유할 수 있는 경우 소스 코드 관리에 체크 인할 수 있습니다.

비밀 값은 파일에서 읽습니다. 따라서 암호를 사용하는 각 자리 표시자에 대해 비밀 값이 포함된 텍스트 파일을 만들어야 합니다.

예를 들어 $[secret:server_password]을(를) 사용하는 경우 server_password​라는 텍스트 파일을 만들어야 합니다. 이러한 모든 비밀 파일은 동일한 디렉토리에 저장해야 하며 프레임워크 속성 org.apache.felix.configadmin.plugin.interpolation.secretsdir은 해당 로컬 디렉터리로 구성해야 합니다.

작성자 및 게시 구성

OSGI 속성에 작성자와 게시에 서로 다른 값이 필요한 경우:

  • 런타임 모드 해상도 섹션에 설명된 대로 별도의 config.authorconfig.publish OSGi 폴더를 사용해야 합니다.
  • 독립적인 변수 이름을 사용해야 합니다. 변수 이름이 동일한 author_<variablename>publish_<variablename> 접두어를 사용하는 것이 좋습니다.

구성 예

아래 예에서 단계 및 prod 환경 외에 3개의 개발 환경이 있다고 가정합니다.

예 1

의도는 OSGI 속성 my_var1 값이 스테이지와 prod에 대해 동일하지만 3개의 개발 환경에 따라 다릅니다.

폴더 myfile.cfg.json의 컨텐츠
config
{ 
 "my_var1":"val",
 "my_var2":"abc",
 "my_var3":500년
}
config.dev
{ 
 "my_var1" :"$[env:my_var1]"
 "my_var2":"abc",
 "my_var3":500년
}

예 2

의도는 OSGI 속성 my_var1 값이 단계, prod 및 3개의 개발 환경에 대해 각각 다르게 하기 위한 것입니다. 따라서 각 개발 env에 대해 my_var1의 값을 설정하려면 클라우드 관리자 API를 호출해야 합니다.

폴더 myfile.cfg.json의 컨텐츠
config.stage
{ 
 "my_var1":"val1",
 "my_var2":"abc",
 "my_var3":500년
}
config.prod
{ 
 "my_var1":"val2",
 "my_var2":"abc",
 "my_var3":500년
}
config.dev
{ 
 "my_var1" :"$[env:my_var1]"
 "my_var2":"abc",
 "my_var3":500년
}

예 3

의도하는 것은 OSGi 속성 my_var1 값이 스테이지, 프로덕션 및 개발 환경 중 하나에 대해 동일하지만 다른 두 개발 환경에 대해서는 다릅니다. 이 경우 준비 및 프로덕션과 동일한 값을 가져야 하는 개발 환경을 포함하여 각 개발 환경에 대해 my_var1 값을 설정하려면 클라우드 관리자 API를 호출해야 합니다. config 폴더에 설정된 값을 상속하지 않습니다.

폴더 myfile.cfg.json의 컨텐츠
config
{ 
 "my_var1":"val1",
 "my_var2":"abc",
 "my_var3":500년
}
config.dev
{ 
 "my_var1" :"$[env:my_var1]"
 "my_var2":"abc",
 "my_var3":500년
}

이를 위한 또 다른 방법은 config.dev 폴더에 있는 교체 토큰의 기본값을 설정하여 config 폴더에 있는 값과 동일한 값을 설정합니다.

폴더 myfile.cfg.json의 컨텐츠
config
{ 
 "my_var1":"val1",
 "my_var2":"abc",
 "my_var3":500년
}
config.dev
{ 
 "my_var1":"$[env:my_var1;default=val1]"
 "my_var2":"abc",
 "my_var3":500년
}

속성 설정에 대한 클라우드 관리자 API 형식

API를 구성해야 하는 방법에 대해서는 이 페이지을 참조하십시오.

노트

사용된 클라우드 관리자 API에 "배포 관리자 - Cloud Service" 역할이 할당되었는지 확인합니다. 다른 역할은 아래 명령을 모두 실행할 수 없습니다.

API를 통해 값 설정

API를 호출하면 일반적인 고객 코드 배포 파이프라인과 유사한 새로운 변수와 값이 클라우드 환경에 배포됩니다. 작성자 및 게시 서비스가 다시 시작되고 새 값을 참조하며 일반적으로 몇 분 정도 걸립니다.

PATCH /program/{programId}/environment/{environmentId}/variables
]
        {
                "name" : "MY_VAR1",
                "value" : "plaintext value",
                "type" : "string"  <---default
        },
        {
                "name" : "MY_VAR2",
                "value" : "<secret value>",
                "type" : "secretString"
        }
]
노트

기본 변수는 API를 통해 설정되지 않고 OSGi 속성 자체에서 설정됩니다.

자세한 내용은 이 페이지를 참조하십시오.

API를 통해 값 가져오기

GET /program/{programId}/environment/{environmentId}/variables

자세한 내용은 이 페이지를 참조하십시오.

API를 통해 값 삭제

PATCH /program/{programId}/environment/{environmentId}/variables

변수를 삭제하려면 빈 값과 함께 포함하십시오.

자세한 내용은 이 페이지를 참조하십시오.

명령줄을(를) 통해 값 가져오기

$ aio cloudmanager:list-environment-variables ENVIRONMENT_ID
Name     Type         Value
MY_VAR1  string       plaintext value 
MY_VAR2  secretString ****

명령줄을 통해 값 설정

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --variable MY_VAR1 "plaintext value" --secret MY_VAR2 "some secret value"

명령줄을(를) 통해 값 삭제

$ aio cloudmanager:set-environment-variables ENVIRONMENT_ID --delete MY_VAR1 MY_VAR2
노트

Adobe I/O CLI용 클라우드 관리자 플러그인을 사용하여 값을 구성하는 방법에 대한 자세한 내용은 이 페이지를 참조하십시오.

변수 수

환경당 최대 200개의 변수를 선언할 수 있습니다.

보안 및 환경별 구성 값 배포 고려 사항

보안 및 환경별 구성 값은 Git 외부에 있으므로 Cloud Service 배포 메커니즘으로서 정식 Adobe Experience Manager에 속하지 않으므로 사용자는 Cloud Service 배포 과정에서 Adobe Experience Manager을 관리하고 제어하며에 통합해야 합니다.

위에서 언급했듯이 API를 호출하면 일반적인 고객 코드 배포 파이프라인과 유사한 새로운 변수와 값이 클라우드 환경에 배포됩니다. 작성자 및 게시 서비스가 다시 시작되고 새 값을 참조하며 일반적으로 몇 분 정도 걸립니다. 일반적인 코드 배포 중 Cloud Manager에서 실행하는 품질 게이트와 테스트는 이 프로세스 동안 수행되지 않습니다.

일반적으로 고객은 Cloud Manager에서 해당 변수에 의존하는 코드를 배포하기 전에 API를 호출하여 환경 변수를 설정합니다. 코드가 이미 배포된 후 기존 변수를 수정할 수도 있습니다.

노트

이 때 최종 파이프라인의 어느 부분이 실행되고 있는지에 따라 파이프라인이 사용 중일 때 AEM 업데이트 또는 고객 배포 중 어느 부분을 사용하는지에 따라 API가 성공할 수 없습니다. 이 오류 응답에는 요청이 성공을 거두지 못했으나 구체적인 이유가 나타나지 않습니다.

예약된 고객 코드 배포가 기존 변수에 의존하여 현재 코드에 맞지 않는 새 값을 갖는 시나리오가 있을 수 있습니다. 이것이 염려되는 경우 부가적인 방식으로 변수를 수정하는 것이 좋습니다. 이렇게 하려면 이전 코드가 새 값을 참조하지 않도록 이전 변수의 값만 변경하는 대신 새 변수 이름을 만드십시오. 그런 다음 새 고객 릴리스가 안정적일 때 이전 값을 제거하도록 선택할 수 있습니다.

마찬가지로 변수 값의 버전이 관리되지 않으므로 코드를 롤백하면 문제를 일으키는 새 값을 참조할 수 있습니다. 이전에 언급한 추가 변수 전략도 여기에 도움이 됩니다.

이 추가 변수 전략은 재배포하기 며칠 전의 코드가 필요한 경우, 변수 이름과 참조하는 값이 그대로 유지되는 재해 복구 시나리오에 유용합니다. 이것은 고객이 이러한 이전 변수를 제거하기 전에 며칠 동안 대기하는 전략에 의존하며, 그렇지 않은 경우 이전 코드에 참조할 적절한 변수가 없을 수 있습니다.

이 페이지에서는

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now
Adobe Maker Awards Banner

Time to shine!

Apply now for the 2021 Adobe Experience Maker Awards.

Apply now