K9 Ownership Byod Setup

BYOD Preferences Reference Table Setup

Help customers create and upload a k9_ownership_preferences reference table to customize how the Ownership Agent determines resource owners.

Read first

• references/schema.md — full schema, column details, validation rules, and per-type examples
• assets/example.csv — complete working CSV with all three preference types

Overview

The Ownership Agent infers owners for cloud resources with security findings. Ownership preferences let customers customize this by providing rules in a Datadog reference table. The agent reads them automatically.

With preferences you can:

• Map tags to owners: Resources with specific tag values belong to a particular team or person
• Exclude accounts: Prevent bot accounts or shared infrastructure from appearing as owners
• Provide custom guidance: Give the AI engine organization-specific context

Reference Table Details

• Table name: k9_ownership_preferences (exact name, must match)
• Effect delay: Changes take effect within 24 hours of upload
• Schema: 12 columns, all STRING — see references/schema.md for details

Workflow

Step 1: Determine Needs

Ask the customer:

• Tag mappings: "Do you have tags on your cloud resources that indicate ownership? (e.g., cost-center, team, project)"
• Exclusions: "Are there bot accounts, service accounts, or shared accounts that should never appear as owners?"
• Prompt text: "Any organization-specific context that would help determine ownership? (e.g., naming conventions, team structure)"

Step 2: Generate CSV

Read references/schema.md for the full column spec and assets/example.csv for a working template. Build a CSV with all 12 column headers. Each row gets a unique sequential id and fills columns relevant to its preference_type, leaving the rest empty.

Step 3: Upload Instructions

Option A — CSV Upload (UI): 1. Go to Integrations > Reference Tables in Datadog 2. Click New Reference Table 3. Upload the CSV 4. Set table name to k9_ownership_preferences 5. Choose primary key: preference_type, tag_key, tag_value, handle 6. Save

Manual uploads support files up to 4 MB.

Option B — Cloud Storage Sync (S3, Azure Blob, GCS): Best for automated, recurring updates. Store your CSV in a cloud storage bucket and Datadog periodically imports it. 1. Upload CSV to S3 / Azure Blob / GCS 2. In Datadog, go to Integrations > Reference Tables 3. Click New Reference Table, select Cloud Storage as source 4. Provide storage path and credentials 5. Set table name to k9_ownership_preferences 6. Datadog re-imports the file periodically

Cloud storage uploads support files up to 200 MB.

Option C — Terraform: Use the datadog_reference_table resource in the Datadog Terraform provider to manage the table as infrastructure-as-code.

Option D — API: You can manage reference tables programmatically through the Reference Tables API. See the API documentation for available endpoints. Replace the API domain with your Datadog site URL if applicable.

Step 4: Verify

Changes take effect within 24 hours. To verify: 1. Identify a resource that matches one of your tag mappings 2. After 24 hours, check the ownership suggestion for that resource in the Datadog UI 3. The suggested owner should reflect your configured mapping

Key Behaviors

• Case-insensitive matching: Tag keys, tag values, handles, exclusion types, and resource types are all matched case-insensitively
• AND-logic exclusions: All non-empty exclusion fields must match. Empty fields act as wildcards
• Tag mappings complement, not override: Direct ownership indicators (like team: or service: tags) take precedence. Tag mappings augment, not replace
• Graceful degradation: If the table doesn't exist or is empty, ownership detection works normally without preferences
• Empty table clears preferences: Deleting all rows or deleting the table causes cached preferences to expire and be left empty
• All-or-nothing validation: Any validation failure rejects the entire preference set for that cycle

Troubleshooting

k9_ownership_preferences Schema Reference

Schema (12 columns, all STRING)

CSV Header

id,preference_type,tag_key,tag_value,owner,confidence,owner_type,handle,exclusion_type,exclusion_resource_type,prompt_text,priority

Each row gets a unique sequential id and fills columns relevant to its preference_type, leaving the rest empty.

Preference Types

Tag Mappings

A tag mapping says: _"When a resource has tag X:Y, it belongs to this owner."_

The agent checks cloud resource tags against your mappings. When a match is found, the specified owner is added as a candidate. Multiple mappings can match the same resource, producing multiple candidates ranked alongside other data sources.

Tag mappings complement existing data sources — they do not override a direct ownership tag (like dd-team) already on the resource.

Columns: id (required), preference_type=tag_mapping, tag_key (required), tag_value (optional, empty=wildcard), owner (required), confidence (required: high/medium/low), owner_type (required: team/user/service).

Owner type guidance:

Confidence guidance:

Matching behavior:

• Tag key and value matching is case-insensitive. Cost-Center matches cost-center.
• An empty tag_value matches any value for that tag key (wildcard).
• If multiple mappings match, all produce candidates. The agent ranks them by confidence.

Example rows:

1,tag_mapping,cost-center,CC-100,team-platform,high,team,,,,,
2,tag_mapping,managed-by,,team-infra,low,team,,,,,

Exclusions

An exclusion says: _"Never assign this handle as a resource owner."_

Bot accounts, CI runners, and shared service accounts often appear in cloud resource metadata. Exclusions remove these from ownership results.

Columns: id (required), preference_type=exclusion, handle (required), exclusion_type (optional), exclusion_resource_type (optional).

Matching behavior:

• The handle is matched case-insensitively.
• Optional filters use AND logic. All non-empty fields must match for the exclusion to apply.
• Leave exclusion_type and exclusion_resource_type empty to exclude from all results (most common).

Example rows:

1,exclusion,,,,,,deploy-bot,,,,
2,exclusion,,,,,,ci-runner,service,,,
3,exclusion,,,,,,k8s-node-controller,service,aws_ec2_instance,,

Custom Prompt Text

Custom prompt text provides free-form guidance to the AI inference engine. Use it to share organizational context: naming conventions, team structures, which data sources to prioritize.

Up to 3 entries, one per priority level (high, medium, low). Entries with the same priority are concatenated.

Columns: id (required), preference_type=prompt_text, prompt_text (required, up to 4096 bytes), priority (optional, default: low).

Tips for effective guidance:

• Be specific and actionable: "The cost-center tag is our most reliable ownership signal" > "Use tags"
• Use plain, declarative sentences — describe facts, not instructions to the AI
• Avoid special formatting: Markdown, HTML, XML tags are stripped during processing

Example rows:

1,prompt_text,,,,,,,,,Our organization assigns ownership by cost center.,high
2,prompt_text,,,,,,,,,Shared infrastructure accounts should never be resource owners.,medium

Validation Rules

All-or-nothing: If any row fails validation, the entire preference set is rejected for that sync cycle. Preferences are left empty until a valid set is uploaded.

Allowed Characters

Not allowed in any field: Angle brackets (< >), curly braces ({ }), pipe characters (|).

Size Limits

Duplicate Detection

The agent rejects the entire set if it contains conflicts:

• Tag mappings: Same tag_key+tag_value with different owner = conflict. Same key+value+owner with different confidence = conflict. Exact duplicates are allowed.
• Exclusions: Same handle+exclusion_type+exclusion_resource_type = duplicate. Case-insensitive.