Support windows platforms

Author: ojproductions

packages/plugin-ecs-fargate/README.md

@@ -40,6 +40,12 @@ The Agent sidecar accepts custom metrics over DogStatsD: `DD_DOGSTATSD_ORIGIN_DE
 
 Running the command twice is safe: the Agent container is matched by name, so an already instrumented task definition is reported as such and no revision is registered. Each revision the command registers is tagged `dd_sls_ci` with the version of `datadog-ci` that created it; upgrading the CLI does not on its own produce a new revision, since that tag is not part of the comparison.
 
+#### Windows tasks
+
+Windows task definitions are instrumented the same way, with three differences the command applies on its own after reading the task's `runtimePlatform`. The Agent runs the `-servercore` build of the image, published as a manifest list so ECS pulls the variant matching your Windows Server version. The Agent container is given `C:\` as its working directory, which it needs and its image does not set. And it gets no health check, because the Agent's probe is a shell script that only the Linux image ships, so a probe would report the Agent as permanently unhealthy rather than tell you anything; the command warns when it makes this choice.
+
+If you pass `--agent-image` for a Windows task, it is used exactly as given, so point it at a `-servercore` tag: mirroring `public.ecr.aws/datadog/agent:latest` into your own registry gives you the Linux image, which will not start on Windows.
+
 #### Deploying the new revision
 
 Pass `--ecs-service` for each service that should run the revision the command just registered, and `--cluster` if those services are not in the `default` cluster. A service named by its full ARN already says which cluster it runs in, so `--cluster` can be left off; passing a `--cluster` that contradicts the ARN's cluster is an error, not a silent override. A run updates services in a single cluster, so ARNs naming more than one are reported too. Each service is matched to the task definition family it currently runs, so a run over several task definitions points each service at its own new revision, and a service already running the instrumented revision is left alone rather than redeployed. Updating a service starts an ECS deployment: the command returns as soon as ECS accepts it, and the rollout follows your service's deployment configuration.

packages/plugin-ecs-fargate/src/__tests__/fixtures.ts

@@ -21,7 +21,7 @@ export const SERVICE_TAG: Tag = {key: 'service', value: MOCK_FAMILY}
 /** The tags every instrumented revision carries. */
 export const INSTRUMENTATION_TAGS: Tag[] = [SERVICE_TAG, CLI_VERSION_TAG]
 
-/** No `agentImage`, so the transform picks the default build. */
+/** No `agentImage`, so the transform picks the default build for the task's platform. */
 export const MOCK_SETTINGS: InstrumentSettings = {
   site: 'datadoghq.com',
   apiKeySecretArn: MOCK_API_KEY_SECRET_ARN,
@@ -69,6 +69,15 @@ export const fargateTaskDefinition = ({
   ...overrides,
 })
 
+/**
+ * A task definition that runs Windows containers, which the Agent sidecar is built differently for.
+ */
+export const windowsTaskDefinition = (overrides: Partial<TaskDefinition> = {}): TaskDefinition =>
+  fargateTaskDefinition({
+    runtimePlatform: {operatingSystemFamily: 'WINDOWS_SERVER_2022_CORE', cpuArchitecture: 'X86_64'},
+    ...overrides,
+  })
+
 /**
  * An ECS service as `DescribeServices` returns it, running the first revision of its family.
  */

packages/plugin-ecs-fargate/src/__tests__/task-definition.test.ts

@@ -1,4 +1,4 @@
-import type {ContainerDefinition} from '@aws-sdk/client-ecs'
+import type {ContainerDefinition, RuntimePlatform} from '@aws-sdk/client-ecs'
 
 import {AGENT_IMAGE} from '@datadog/datadog-ci-base/helpers/serverless/constants'
 
@@ -14,6 +14,7 @@ import {
   MOCK_SETTINGS,
   SERVICE_TAG,
   fargateTaskDefinition,
+  windowsTaskDefinition,
 } from './fixtures'
 
 jest.mock('@datadog/datadog-ci-base/version', () => ({cliVersion: 'XXXX'}))
@@ -537,6 +538,68 @@ describe('instrumentTaskDefinition', () => {
     })
   })
 
+  describe('windows tasks', () => {
+    test('runs the Windows build of the Agent image', () => {
+      const {taskDefinition} = instrumentTaskDefinition(windowsTaskDefinition(), MOCK_SETTINGS)
+
+      expect(agentContainerOf(taskDefinition.containerDefinitions)?.image).toBe(`${AGENT_IMAGE}-servercore`)
+    })
+
+    test('gives the Agent the working directory its Windows image leaves unset', () => {
+      const {taskDefinition} = instrumentTaskDefinition(windowsTaskDefinition(), MOCK_SETTINGS)
+
+      expect(agentContainerOf(taskDefinition.containerDefinitions)?.workingDirectory).toBe('C:\\')
+    })
+
+    test('adds no health check, since the Agent probe only ships in the Linux image', () => {
+      const {taskDefinition, warnings} = instrumentTaskDefinition(windowsTaskDefinition(), MOCK_SETTINGS)
+
+      expect(agentContainerOf(taskDefinition.containerDefinitions)).not.toHaveProperty('healthCheck')
+      expect(warnings).toContainEqual(expect.stringContaining('without a health check'))
+    })
+
+    test('still runs an explicitly requested image', () => {
+      const {taskDefinition} = instrumentTaskDefinition(windowsTaskDefinition(), {
+        ...MOCK_SETTINGS,
+        agentImage: 'my-registry/agent:7.60.0-servercore',
+      })
+
+      expect(agentContainerOf(taskDefinition.containerDefinitions)?.image).toBe('my-registry/agent:7.60.0-servercore')
+    })
+
+    test('instruments the application containers as it would on Linux', () => {
+      const {taskDefinition} = instrumentTaskDefinition(windowsTaskDefinition(), {
+        ...MOCK_SETTINGS,
+        service: 'payments',
+      })
+
+      const app = appContainerOf(taskDefinition.containerDefinitions)
+      expect(envVarsOf(app)).toHaveProperty('DD_SERVICE', 'payments')
+      expect(app?.dockerLabels).toStrictEqual({'com.datadoghq.tags.service': 'payments'})
+    })
+
+    test('re-instrumenting produces an identical task definition', () => {
+      const first = instrumentTaskDefinition(windowsTaskDefinition(), MOCK_SETTINGS)
+      const described = windowsTaskDefinition({containerDefinitions: first.taskDefinition.containerDefinitions})
+
+      const second = instrumentTaskDefinition(described, MOCK_SETTINGS)
+
+      expect(second.taskDefinition).toStrictEqual(first.taskDefinition)
+    })
+
+    test.each<[string, RuntimePlatform | undefined]>([
+      ['LINUX', {operatingSystemFamily: 'LINUX', cpuArchitecture: 'X86_64'}],
+      ['no runtime platform', undefined],
+    ])('builds the Linux Agent for a task declaring %s', (_, runtimePlatform) => {
+      const {taskDefinition} = instrumentTaskDefinition(fargateTaskDefinition({runtimePlatform}), MOCK_SETTINGS)
+
+      const agent = agentContainerOf(taskDefinition.containerDefinitions)
+      expect(agent?.image).toBe(AGENT_IMAGE)
+      expect(agent?.healthCheck).toBeDefined()
+      expect(agent).not.toHaveProperty('workingDirectory')
+    })
+  })
+
   describe('validation', () => {
     test('rejects a task definition that is not awsvpc', () => {
       const original = fargateTaskDefinition({networkMode: 'bridge'})

packages/plugin-ecs-fargate/src/commands/instrument.ts

@@ -235,6 +235,9 @@ export class PluginCommand extends EcsFargateInstrumentCommand {
 
   /**
    * What the task definitions are instrumented with, leaving aside how the Agent gets its API key.
+   *
+   * The Agent image is left as the user gave it, absent included: the default depends on whether the
+   * task runs Linux or Windows, which only the transform reading the task definition can tell.
    */
   private buildSettings(config: EcsFargateConfigOptions): InstrumentSettings {
     return {

packages/plugin-ecs-fargate/src/constants.ts

@@ -17,9 +17,26 @@ export const LAUNCH_TYPE_FARGATE = 'FARGATE'
  */
 export const AWSVPC_NETWORK_MODE = 'awsvpc'
 
+/**
+ * ECS spells the Windows operating system families with the `WINDOWS_SERVER` prefix (e.g.
+ * `WINDOWS_SERVER_2019_CORE`, `WINDOWS_SERVER_2022_FULL`) Anything else, `LINUX` and
+ * declaring no family at all included, runs Linux.
+ */
+export const WINDOWS_OS_FAMILY_PREFIX = 'WINDOWS_SERVER'
+
 // Agent sidecar defaults
 export const AGENT_CONTAINER_NAME = 'datadog-agent'
 
+/**
+ * The tag suffix for the Windows build of the Agent image
+ */
+export const WINDOWS_AGENT_IMAGE_SUFFIX = '-servercore'
+
+/**
+ * The working directory the Agent requires on Windows, which its image does not set itself.
+ */
+export const WINDOWS_WORKING_DIRECTORY = 'C:\\'
+
 /**
  * The task definition tag keys for the unified service tags, which name the same three concepts as
  * the `DD_SERVICE`, `DD_ENV`, and `DD_VERSION` environment variables the containers run with.
@@ -40,6 +57,9 @@ export const DOCKER_LABEL_VERSION = 'com.datadoghq.tags.version'
 /**
  * The Agent's own health probe. Shipping it means application containers can gate their startup on
  * the Agent being ready through a `dependsOn` HEALTHY condition.
+ *
+ * Linux only: `/probe.sh` is a shell script shipped in the Linux image, and the Windows image has
+ * no equivalent on its `PATH`, so Windows tasks get no health check at all.
  */
 export const AGENT_HEALTH_CHECK_COMMAND = ['CMD-SHELL', '/probe.sh']
 export const AGENT_HEALTH_CHECK_INTERVAL = 15

packages/plugin-ecs-fargate/src/task-definition.ts

@@ -54,15 +54,18 @@ import {
   READ_ONLY_TASK_DEFINITION_FIELDS,
   SERVICE_TAG_KEY,
   VERSION_TAG_KEY,
+  WINDOWS_AGENT_IMAGE_SUFFIX,
+  WINDOWS_OS_FAMILY_PREFIX,
+  WINDOWS_WORKING_DIRECTORY,
 } from './constants'
 
 /**
  * What the user asked for, resolved into the decisions the transform needs.
  */
 export type InstrumentSettings = {
   /**
-   * The Agent image to run. Absent leaves the choice to the transform, which picks the default
-   * build.
+   * The Agent image to run. Absent leaves the choice to the transform, which picks the default build
+   * for the task's platform.
    */
   agentImage?: string
   site: string
@@ -276,11 +279,26 @@ export type AgentContainerResult = {
   warnings: string[]
 }
 
+/**
+ * Whether the task runs Windows containers, which the Agent sidecar has to be built differently
+ * for. A task definition that declares no `runtimePlatform`, or declares `LINUX`, runs Linux.
+ */
+const isWindowsTask = (taskDefinition: TaskDefinition): boolean =>
+  taskDefinition.runtimePlatform?.operatingSystemFamily?.toUpperCase().startsWith(WINDOWS_OS_FAMILY_PREFIX) ?? false
+
+/**
+ * The Agent image to run; either the one specified by the user, or the default build for the task's platform.
+ */
+const agentImage = (settings: InstrumentSettings, windows: boolean): string =>
+  settings.agentImage ?? (windows ? `${AGENT_IMAGE}${WINDOWS_AGENT_IMAGE_SUFFIX}` : AGENT_IMAGE)
+
 /**
  * What the Agent sidecar is built from.
  */
 type AgentContainerContext = {
   settings: InstrumentSettings
+  /** Whether the task runs Windows containers. */
+  windows: boolean
   /** The task definition family, used to name the service when the user did not. */
   family?: string
   /** The Agent container already on the task definition, if any. */
@@ -296,6 +314,7 @@ type AgentContainerContext = {
  */
 const buildAgentContainer = ({
   settings,
+  windows,
   family,
   existing,
   logConfiguration,
@@ -323,27 +342,37 @@ const buildAgentContainer = ({
     )
   }
 
-  const healthCheck = {
-    command: [...AGENT_HEALTH_CHECK_COMMAND],
-    interval: AGENT_HEALTH_CHECK_INTERVAL,
-    timeout: AGENT_HEALTH_CHECK_TIMEOUT,
-    retries: AGENT_HEALTH_CHECK_RETRIES,
-    startPeriod: AGENT_HEALTH_CHECK_START_PERIOD,
-  }
-  if (existing?.healthCheck && !sortedEqual(existing.healthCheck, healthCheck)) {
+  // The Agent's probe is a shell script that only exists in the Linux image, so a Windows task gets
+  // no health check rather than one that can never pass.
+  const healthCheck = windows
+    ? undefined
+    : {
+        command: [...AGENT_HEALTH_CHECK_COMMAND],
+        interval: AGENT_HEALTH_CHECK_INTERVAL,
+        timeout: AGENT_HEALTH_CHECK_TIMEOUT,
+        retries: AGENT_HEALTH_CHECK_RETRIES,
+        startPeriod: AGENT_HEALTH_CHECK_START_PERIOD,
+      }
+  if (windows) {
+    warnings.push(
+      `Leaving the ${AGENT_CONTAINER_NAME} container without a health check: the Agent's probe is a shell script that only its Linux image ships. Nothing will report whether the Agent is ready on this task.`
+    )
+  } else if (existing?.healthCheck && !sortedEqual(existing.healthCheck, healthCheck)) {
     warnings.push(`Replacing the health check on the ${AGENT_CONTAINER_NAME} container with the Agent's own probe.`)
   }
 
   const container = removeUndefinedValues({
     ...existing,
     name: AGENT_CONTAINER_NAME,
-    image: settings.agentImage ?? AGENT_IMAGE,
+    image: agentImage(settings, windows),
     // The Agent must not be able to take the task down: a crashed Agent should cost telemetry, not
     // availability.
     essential: false,
     environment: toEnvironment(getAgentEnvVars(settings, family), inheritedEnvironment),
     secrets,
     healthCheck,
+    // The Windows Agent image leaves the working directory unset, and the Agent needs one.
+    workingDirectory: windows ? WINDOWS_WORKING_DIRECTORY : existing?.workingDirectory,
     // Without one, a Fargate container's output goes nowhere, which would leave an Agent that
     // cannot pull its image or reach Datadog impossible to diagnose.
     logConfiguration: existing?.logConfiguration ?? logConfiguration,
@@ -429,6 +458,7 @@ export const instrumentTaskDefinition = (
   const existingAgent = containers.find((container) => container.name === AGENT_CONTAINER_NAME)
   const {container: agentContainer, warnings} = buildAgentContainer({
     settings,
+    windows: isWindowsTask(taskDefinition),
     family,
     existing: existingAgent,
     logConfiguration: borrowedLogConfiguration(containers),