How to Configure Environment-Specific ETC MAPs for AEM as a Cloud Service?

 

Photo by Alvaro Reyes on Unsplash

In Adobe Experience Manager (AEM), managing environment-specific ETC maps is crucial for defining DNS content mappings to support multiple domains and to enable resource mapping and resolution. For detailed guidance on resource resolution in AEM, refer to the post “Configure Sling Mappings for Resource Resolution in Adobe Experience Manager(AEM) — Deep Dive | by Albin Issac | Medium”.

Key Configurations:

• ETC Map Usage: The ETC map, used in conjunction with the JCR Resource Resolver, supports resource resolution and mapping across multiple domains. Unfortunately, ETC map configurations do not consider run modes during the application, necessitating a combination with run mode-specific configurations using org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl
• Creating Environment-Specific Folders: Create specific /etc/map folders like /etc/map.dev.publish, /etc/map.uat.publish, /etc/map.stage.publish, and /etc/map.prod.publish

Run Mode-Specific JCR Resolver Configurations: These should be set up as follows:

Dev/Publish(config.dev.publish) run modes: org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.cfg.json

resource.resolver.map.location”: “/etc/map.dev.publish”

{
  "resource.resolver.map.observation": ["/libs", "/apps", "/content", "/etc", "/conf"],
  "resource.resolver.searchpath": ["/apps", "/libs", "/apps/foundation/components/primary", "/libs/foundation/components/primary"],
  "resource.resolver.required.providers": ["org.apache.sling.jcr.resource.internal.helper.jcr.JcrResourceProviderFactory"],
  "resource.resolver.default.vanity.redirect.status": 302,
  "resource.resolver.mapping": ["/-/"],
  "resource.resolver.virtual": ["/:/"],
  "resource.resolver.vanitypath.whitelist": ["/apps/", "/libs/", "/content/"],
  "resource.resolver.manglenamespaces": true,
  "resource.resolver.map.location": "/etc/map.dev.publish",
  "resource.resolver.log.unclosed": false,
  "resource.resolver.allowDirect": true,
  "resource.resolver.vanitypath.blacklist": ["/content/usergenerated"]
}

Stage/Publish(config.stage.publish) run modes: org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.cfg.json

resource.resolver.map.location”: “/etc/map.stage.publish”

{
  "resource.resolver.map.observation": ["/libs", "/apps", "/content", "/etc", "/conf"],
  "resource.resolver.searchpath": ["/apps", "/libs", "/apps/foundation/components/primary", "/libs/foundation/components/primary"],
  "resource.resolver.required.providers": ["org.apache.sling.jcr.resource.internal.helper.jcr.JcrResourceProviderFactory"],
  "resource.resolver.default.vanity.redirect.status": 302,
  "resource.resolver.mapping": ["/-/"],
  "resource.resolver.virtual": ["/:/"],
  "resource.resolver.vanitypath.whitelist": ["/apps/", "/libs/", "/content/"],
  "resource.resolver.manglenamespaces": true,
  "resource.resolver.map.location": "/etc/map.stage.publish",
  "resource.resolver.log.unclosed": false,
  "resource.resolver.allowDirect": true,
  "resource.resolver.vanitypath.blacklist": ["/content/usergenerated"]
}

Prod/Publish(config.prod.publish) run modes: org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.cfg.json

“resource.resolver.map.location”: “/etc/map.prod.publish”

{
  "resource.resolver.map.observation": ["/libs", "/apps", "/content", "/etc", "/conf"],
  "resource.resolver.searchpath": ["/apps", "/libs", "/apps/foundation/components/primary", "/libs/foundation/components/primary"],
  "resource.resolver.required.providers": ["org.apache.sling.jcr.resource.internal.helper.jcr.JcrResourceProviderFactory"],
  "resource.resolver.default.vanity.redirect.status": 302,
  "resource.resolver.mapping": ["/-/"],
  "resource.resolver.virtual": ["/:/"],
  "resource.resolver.vanitypath.whitelist": ["/apps/", "/libs/", "/content/"],
  "resource.resolver.manglenamespaces": true,
  "resource.resolver.map.location": "/etc/map.prod.publish",
  "resource.resolver.log.unclosed": false,
  "resource.resolver.allowDirect": true,
  "resource.resolver.vanitypath.blacklist": ["/content/usergenerated"]
}

Challenges and Solutions for Dev Environments:

Although Stage and Prod environments load specific ETC maps properly, the challenge arises in Dev environments. These are always enabled with a Dev run mode but can be designated for various purposes like Development or UAT. This mismatch can cause disruptions if not handled correctly.

Integrating with Cloud Manager Variables:

To address this, combine the approach with Cloud Manager Variables. Cloud Manager allows for the setting of environment-specific variables that can be referenced in JAVA, OSGI, and Dispatcher configurations — Refer to Support Custom Run Modes in AEM as a Cloud | Environment Specific Variables in AEM as a Cloud | by Albin Issac | Tech Learnings | Medium for more details.

Define an ETC_MAP_PATH variable in Cloud Manager corresponding to the environment-specific ETC MAP path (e.g., /etc/map.dev.publish, /etc/map.uat.publish) and apply this variable to the Publish environment. This approach ensures uniformity across all environments, including Stage and Prod.

Applying the Configuration: (config.publish) — org.apache.sling.jcr.resource.internal.JcrResourceResolverFactoryImpl.cfg.json

“resource.resolver.map.location”: “$[env:ETC_MAP_PATH]”

{
  "resource.resolver.map.observation": ["/libs", "/apps", "/content", "/etc", "/conf"],
  "resource.resolver.searchpath": ["/apps", "/libs", "/apps/foundation/components/primary", "/libs/foundation/components/primary"],
  "resource.resolver.required.providers": ["org.apache.sling.jcr.resource.internal.helper.jcr.JcrResourceProviderFactory"],
  "resource.resolver.default.vanity.redirect.status": 302,
  "resource.resolver.mapping": ["/-/"],
  "resource.resolver.virtual": ["/:/"],
  "resource.resolver.vanitypath.whitelist": ["/apps/", "/libs/", "/content/"],
  "resource.resolver.manglenamespaces": true,
  "resource.resolver.map.location": "$[env:ETC_MAP_PATH]",
  "resource.resolver.log.unclosed": false,
  "resource.resolver.allowDirect": true,
  "resource.resolver.vanitypath.blacklist": ["/content/usergenerated"]
}

This refined approach ensures each cloud environment loads the ETC map based on the path specified in the Cloud Manager variable ETC_MAP_PATH, allowing for precise environment-specific resource mapping.