
devops-cloud
AWS, Azure, GCP, Cloudflare, serverless and multi-cloud
- version
- 1.0.0
- GitHub stars
- 5
Install
/plugin install devops-cloud@skills-stackRun it inside Claude Code after adding the marketplace with /plugin marketplace add marslanalvi/SkillsStack.
Contents
Discovered from sourceSkills 26
AWS Bedrock AgentCore
When to Use
Use this skill when you need aWS Bedrock AgentCore comprehensive expert for deploying and managing AI agents at scale. Use when working with any AgentCore service including Gateway, Runtime, Memory, Identity, Code Interpreter, Browser, Observability, Agent Registry, or Evaluations. Covers agent deployment, MCP...
AWS Bedrock AgentCore provides a complete platform for deploying and scaling AI agents with nine core services. This skill covers service selection, deployment patterns, and integration workflows using AWS CLI.
How to use this skill: Identify the service(s) the user needs from the table below, then read the corresponding service README before responding. For cross-service patterns (credentials, security, registry integration), check the Cross-Service Resources section. Verify AWS-specific details using the MCP documentation tools.
AWS Documentation Requirement
Verify current AWS facts through available primary documentation tools or official AWS documentation. The following are optional upstream integrations, not tools bundled by this single-file catalog skill:
- AgentCore-specific docs (
mcp__acdocs__*) — upstream integration that may providesearch_agentcore_docsandfetch_agentcore_docfor AgentCore documentation - General AWS docs (
mcp__aws-mcp__*ormcp__*awsdocs*__*) — may be configured separately for broader AWS documentation
Prefer the AgentCore docs MCP for AgentCore-specific questions. If these tools are unavailable, use official documentation; do not install a new server unless requested.
Available Services
| Service | Use For | Documentation |
|---|---|---|
| Gateway | Converting REST APIs to MCP tools | services/gateway/README.md |
| Runtime | Deploying and scaling agents | services/runtime/README.md |
| Memory | Managing conversation state | services/memory/README.md |
| Identity | Credential and access management | services/identity/README.md |
| Code Interpreter | Secure code execution in sandboxes | services/code-interpreter/README.md |
| Browser | Web automation and scraping | services/browser/README.md |
| Observability | Tracing and monitoring | services/observability/README.md |
| Agent Registry | Catalog, discover, and govern agents/tools (Preview) | services/registry/README.md |
| Evaluations | Automated agent quality assessment (LLM-as-a-Judge) | services/evaluations/README.md |
This catalog contains no service README or executable templates locally. Read the selected upstream revision and inspect every dependency before implementation; do not claim those references were reviewed from their titles. Verify account/region/IAM, costs, data retention and publication scope before provisioning or sending conversation/trace data to cloud services.
Common Workflows
Deploying a Gateway Target
Read services/gateway/README.md before implementing — Gateway setup involves deployment strategies, IAM, and auth choices that vary significantly by use case.
- Upload OpenAPI schema to S3
- (API Key auth only) Create credential provider and store API key
- Create gateway target linking schema (and credentials if using API key)
- Verify target status and test connectivity
Credential provider is only needed for API key authentication. Lambda targets use IAM roles, and MCP servers use OAuth.
Managing Credentials
Read cross-service/credential-management.md first — credential patterns differ across services and getting them wrong causes hard-to-debug auth failures.
- Use Identity service credential providers for all API keys
- Link providers to gateway targets via ARN references
- Rotate credentials quarterly through credential provider updates
- Monitor usage with CloudWatch metrics
Discovering Agents and Tools (Agent Registry)
Read services/registry/README.md first — the registry has governance workflows, MCP endpoint options, and sync modes that affect how records become discoverable.
- Create a registry to catalog your organization's AI resources
- Register resources (MCP servers, agents, skills, custom) with descriptive metadata
- Submit records for approval (auto-approve for dev, manual for production)
- Search and discover approved resources via CLI or MCP endpoint
Verify current Agent Registry release status and regional availability in official AWS documentation before planning a deployment.
Evaluating Agent Quality
Read services/evaluations/README.md first — evaluators, scoring modes, and IAM setup vary between online monitoring and on-demand testing.
- Instrument the agent with OpenTelemetry (ADOT) for trace collection
- Create evaluators (use built-in like
Builtin.Helpfulnessor create custom) - Set up online evaluation with sampling rate and data source
- Monitor scores in CloudWatch dashboards; investigate low-scoring sessions
Monitoring Agents
Read services/observability/README.md for the full monitoring setup — observability configuration depends on your Runtime protocol and framework choice.
- Enable observability for agents
- Configure CloudWatch dashboards for metrics
- Set up alarms for error rates and latency
- Use X-Ray for distributed tracing
Deep-Dive References
Each service README (linked in the table above) contains sub-links to getting-started guides, troubleshooting, and advanced topics. Start with the service README and follow pointers from there.
Advanced Runtime & OAuth References
Deep-dive reference documentation for Runtime internals, deployment, OAuth integration, and communication protocols. Read these when building production Runtime deployments or configuring OAuth authentication:
- OAuth Integration:
references/agentcore-oauth-integration.md- Three-layer OAuth architecture (Inbound JWT, Outbound Credential Provider, Gateway OAuth), Cognito configuration, supported IdPs, end-to-end CDK examples - Runtime Core Mechanisms:
references/agentcore-runtime-core.md- Container contract, MicroVM Session model, Agent lifecycle (per-request vs per-session), tool integration (MCP/HTTP), startup flow - Runtime Deployment & Operations:
references/agentcore-runtime-deploy.md- CDK deployment (L1/L2 constructs), multi-Runtime architecture, security model, observability (OTel/CloudWatch), BedrockAgentCoreApp vs FastAPI comparison - Runtime Protocol Reference:
references/agentcore-runtime-protocols.md- HTTP, MCP, A2A, AG-UI protocol specifications with container contracts, endpoint specs, and selection guide
Runnable Script Templates
External upstream templates (not bundled or production-certified by this review) in scripts/ for common deployment patterns:
| Script | Protocol | Description |
|---|---|---|
Dockerfile.runtime-template | — | ARM64 multi-stage Docker build for AgentCore Runtime |
runtime-fastapi-template.py | HTTP | FastAPI Runtime with SSE streaming and MCPClient |
mcp-server-template.py | MCP | MCP Server with Streamable HTTP transport |
a2a-server-template.py | A2A | A2A Server with Agent Card discovery |
agui-server-template.py | AG-UI | AG-UI Server with standard AG-UI event stream |
gateway-custom-resource-lambda.py | — | CDK Custom Resource Lambda for Gateway lifecycle |
Cross-Service Resources
For patterns and best practices that span multiple AgentCore services:
- Credential Management:
cross-service/credential-management.md- Unified credential patterns, security practices, rotation procedures - Registry Integration:
cross-service/registry-integration.md- Cross-service patterns with Gateway, Identity, Runtime - Security & Resource Policies:
cross-service/security-resource-policies.md- Resource-based policies, cross-account access, VPC/IP restrictions - Agent Deployment with S3 Files:
cross-service/agent-persistence-patterns.md- Deploy Strands Agents, OpenClaw, Claude Agent SDK on AgentCore with S3 Files and Session Storage
Additional Resources
- AWS Documentation: Amazon Bedrock AgentCore
- API Reference: Bedrock AgentCore Control Plane API
- AWS CLI Reference: bedrock-agentcore-control commands
Example
User request:
Use @aws-agentic-ai for this task: AWS Bedrock AgentCore comprehensive expert for deploying and managing AI agents at scale.
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
AWS CloudTrail
Audit AWS account activity with CloudTrail for compliance, security investigation, and operational troubleshooting.
When to Use
- Enabling organization-wide audit logging across all AWS accounts
- Investigating security incidents or unauthorized API activity
- Meeting compliance requirements for SOC 2, HIPAA, PCI DSS, or FedRAMP
- Setting up automated alerting on sensitive AWS API calls
- Querying historical AWS activity for forensic analysis
Prerequisites and Change Scope
Verify the AWS identity, partition, region and organization management/delegated-administrator permissions before mutation. All names, account IDs and ARNs below are synthetic placeholders; choose a globally unique owned bucket. Have a working KMS key policy permitting the selected CloudTrail trail and authorized readers, an existing CloudWatch log group and scoped role/trust policy before passing their ARNs. The snippets do not provision those dependencies. Review paid data-event/Lake/Athena scope and retention costs first. Export existing policies/selectors/lifecycle settings and merge intended changes; put-* operations can replace existing configuration. Never apply expiration to audit evidence under a legal hold.
Create an Organization Trail
# Create the S3 bucket for log storage
aws s3api create-bucket \
--bucket org-cloudtrail-audit-logs \
--region us-east-1
# Apply bucket policy allowing CloudTrail to write
aws s3api put-bucket-policy \
--bucket org-cloudtrail-audit-logs \
--policy '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AWSCloudTrailAclCheck",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:GetBucketAcl",
"Resource": "arn:aws:s3:::org-cloudtrail-audit-logs",
"Condition": {"StringEquals": {"aws:SourceArn": "arn:aws:cloudtrail:us-east-1:123456789012:trail/org-audit-trail"}}
},
{
"Sid": "AWSCloudTrailWrite",
"Effect": "Allow",
"Principal": {"Service": "cloudtrail.amazonaws.com"},
"Action": "s3:PutObject",
"Resource": ["arn:aws:s3:::org-cloudtrail-audit-logs/AWSLogs/123456789012/*", "arn:aws:s3:::org-cloudtrail-audit-logs/AWSLogs/o-exampleorgid/*"],
"Condition": {
"StringEquals": {"s3:x-amz-acl": "bucket-owner-full-control", "aws:SourceArn": "arn:aws:cloudtrail:us-east-1:123456789012:trail/org-audit-trail"}
}
}
]
}'
# Block public access on the audit bucket
aws s3api put-public-access-block \
--bucket org-cloudtrail-audit-logs \
--public-access-block-configuration \
BlockPublicAcls=true,IgnorePublicAcls=true,BlockPublicPolicy=true,RestrictPublicBuckets=true
# Enable version history (not WORM/tamper prevention)
aws s3api put-bucket-versioning \
--bucket org-cloudtrail-audit-logs \
--versioning-configuration Status=Enabled
# Enable server-side encryption
aws s3api put-bucket-encryption \
--bucket org-cloudtrail-audit-logs \
--server-side-encryption-configuration '{
"Rules": [{"ApplyServerSideEncryptionByDefault": {"SSEAlgorithm": "aws:kms", "KMSMasterKeyID": "alias/cloudtrail-key"}}]
}'
# Set lifecycle policy for log retention
aws s3api put-bucket-lifecycle-configuration \
--bucket org-cloudtrail-audit-logs \
--lifecycle-configuration '{
"Rules": [
{
"ID": "TransitionToGlacier",
"Status": "Enabled",
"Filter": {"Prefix": "AWSLogs/"},
"Transitions": [
{"Days": 90, "StorageClass": "GLACIER"}
]
},
{
"ID": "ExpireOldLogs",
"Status": "Enabled",
"Filter": {"Prefix": "AWSLogs/"},
"Expiration": {"Days": 2555}
}
]
}'
# Create the organization trail
aws cloudtrail create-trail \
--name org-audit-trail \
--s3-bucket-name org-cloudtrail-audit-logs \
--is-organization-trail \
--is-multi-region-trail \
--enable-log-file-validation \
--kms-key-id arn:aws:kms:us-east-1:123456789012:alias/cloudtrail-key \
--cloud-watch-logs-log-group-arn arn:aws:logs:us-east-1:123456789012:log-group:CloudTrail:* \
--cloud-watch-logs-role-arn arn:aws:iam::123456789012:role/CloudTrail-CWLogs-Role
# Start logging
aws cloudtrail start-logging --name org-audit-trail
The organization prefix must use the real organization ID and the trail ARN must use the management account ID. Log-file validation detects changes; it does not prevent deletion. Versioning alone is not immutable retention. Validate Object Lock/legal-hold design separately where required.
Event Selectors for Management and Data Events
# Configure advanced event selectors for granular control
aws cloudtrail put-event-selectors \
--trail-name org-audit-trail \
--advanced-event-selectors '[
{
"Name": "AllManagementEvents",
"FieldSelectors": [
{"Field": "eventCategory", "Equals": ["Management"]}
]
},
{
"Name": "S3DataEventsForSensitiveBuckets",
"FieldSelectors": [
{"Field": "eventCategory", "Equals": ["Data"]},
{"Field": "resources.type", "Equals": ["AWS::S3::Object"]},
{"Field": "resources.ARN", "StartsWith": [
"arn:aws:s3:::sensitive-data-bucket/",
"arn:aws:s3:::pii-bucket/",
"arn:aws:s3:::financial-data/"
]}
]
},
{
"Name": "LambdaInvocations",
"FieldSelectors": [
{"Field": "eventCategory", "Equals": ["Data"]},
{"Field": "resources.type", "Equals": ["AWS::Lambda::Function"]}
]
},
{
"Name": "DynamoDBDataEvents",
"FieldSelectors": [
{"Field": "eventCategory", "Equals": ["Data"]},
{"Field": "resources.type", "Equals": ["AWS::DynamoDB::Table"]}
]
}
]'
CloudWatch Alerts for Sensitive Activity
# Create metric filter for unauthorized API calls
aws logs put-metric-filter \
--log-group-name CloudTrail \
--filter-name UnauthorizedAPICalls \
--filter-pattern '{ ($.errorCode = "*UnauthorizedAccess*") || ($.errorCode = "AccessDenied*") }' \
--metric-transformations \
metricName=UnauthorizedAPICalls,metricNamespace=CloudTrailMetrics,metricValue=1
# Create alarm for unauthorized calls
aws cloudwatch put-metric-alarm \
--alarm-name UnauthorizedAPICallsAlarm \
--metric-name UnauthorizedAPICalls \
--namespace CloudTrailMetrics \
--statistic Sum \
--period 300 \
--threshold 5 \
--comparison-operator GreaterThanOrEqualToThreshold \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:us-east-1:123456789012:security-alerts
# Root account usage alarm
aws logs put-metric-filter \
--log-group-name CloudTrail \
--filter-name RootAccountUsage \
--filter-pattern '{ ($.userIdentity.type = "Root") && ($.userIdentity.invokedBy NOT EXISTS) && ($.eventType != "AwsServiceEvent") }' \
--metric-transformations \
metricName=RootAccountUsage,metricNamespace=CloudTrailMetrics,metricValue=1
aws cloudwatch put-metric-alarm \
--alarm-name RootAccountUsageAlarm \
--metric-name RootAccountUsage \
--namespace CloudTrailMetrics \
--statistic Sum \
--period 300 \
--threshold 1 \
--comparison-operator GreaterThanOrEqualToThreshold \
--evaluation-periods 1 \
--alarm-actions arn:aws:sns:us-east-1:123456789012:security-alerts
# Console login without MFA
aws logs put-metric-filter \
--log-group-name CloudTrail \
--filter-name ConsoleLoginWithoutMFA \
--filter-pattern '{ ($.eventName = "ConsoleLogin") && ($.additionalEventData.MFAUsed != "Yes") && ($.userIdentity.type = "IAMUser") }' \
--metric-transformations \
metricName=ConsoleLoginWithoutMFA,metricNamespace=CloudTrailMetrics,metricValue=1
# IAM policy changes
aws logs put-metric-filter \
--log-group-name CloudTrail \
--filter-name IAMPolicyChanges \
--filter-pattern '{ ($.eventName=CreatePolicy) || ($.eventName=DeletePolicy) || ($.eventName=AttachRolePolicy) || ($.eventName=DetachRolePolicy) || ($.eventName=AttachUserPolicy) || ($.eventName=PutUserPolicy) }' \
--metric-transformations \
metricName=IAMPolicyChanges,metricNamespace=CloudTrailMetrics,metricValue=1
# Security group changes
aws logs put-metric-filter \
--log-group-name CloudTrail \
--filter-name SecurityGroupChanges \
--filter-pattern '{ ($.eventName=AuthorizeSecurityGroupIngress) || ($.eventName=RevokeSecurityGroupIngress) || ($.eventName=CreateSecurityGroup) || ($.eventName=DeleteSecurityGroup) }' \
--metric-transformations \
metricName=SecurityGroupChanges,metricNamespace=CloudTrailMetrics,metricValue=1
Athena Queries for CloudTrail Analysis
-- Create Athena table for CloudTrail logs
CREATE EXTERNAL TABLE IF NOT EXISTS cloudtrail_logs (
eventVersion STRING,
userIdentity STRUCT<
type: STRING,
principalId: STRING,
arn: STRING,
accountId: STRING,
invokedBy: STRING,
accessKeyId: STRING,
userName: STRING,
sessionContext: STRUCT<
attributes: STRUCT<mfaAuthenticated: STRING, creationDate: STRING>,
sessionIssuer: STRUCT<type: STRING, principalId: STRING, arn: STRING, accountId: STRING, userName: STRING>
>
>,
eventTime STRING,
eventSource STRING,
eventName STRING,
awsRegion STRING,
sourceIPAddress STRING,
userAgent STRING,
errorCode STRING,
errorMessage STRING,
requestParameters STRING,
responseElements STRING,
additionalEventData STRING,
requestId STRING,
eventId STRING,
readOnly STRING,
resources ARRAY<STRUCT<arn: STRING, accountId: STRING, type: STRING>>,
eventType STRING,
recipientAccountId STRING
)
PARTITIONED BY (region STRING, year STRING, month STRING, day STRING)
ROW FORMAT SERDE 'org.apache.hive.hcatalog.data.JsonSerDe'
STORED AS INPUTFORMAT 'com.amazon.emr.cloudtrail.CloudTrailInputFormat'
OUTPUTFORMAT 'org.apache.hadoop.hive.ql.io.HiveIgnoreKeyTextOutputFormat'
LOCATION 's3://org-cloudtrail-audit-logs/AWSLogs/o-exampleorgid/123456789012/CloudTrail/';
-- Add a known delivered partition before querying (repeat for required account/dates).
ALTER TABLE cloudtrail_logs ADD IF NOT EXISTS
PARTITION (region='us-east-1', year='2026', month='10', day='22')
LOCATION 's3://org-cloudtrail-audit-logs/AWSLogs/o-exampleorgid/123456789012/CloudTrail/us-east-1/2026/10/22/';
-- Find all delete operations in the last 7 days
SELECT eventTime, userIdentity.arn, eventName, sourceIPAddress,
requestParameters
FROM cloudtrail_logs
WHERE eventName LIKE '%Delete%'
AND eventTime > date_format(date_add('day', -7, current_date), '%Y-%m-%dT%H:%i:%sZ')
ORDER BY eventTime DESC
LIMIT 100;
-- Identify console logins outside a synthetic exact-IP allowlist (not CIDR matching)
SELECT eventTime, userIdentity.userName, sourceIPAddress,
additionalEventData
FROM cloudtrail_logs
WHERE eventName = 'ConsoleLogin'
AND sourceIPAddress NOT IN ('198.51.100.10', '203.0.113.20')
AND eventTime > date_format(date_add('day', -30, current_date), '%Y-%m-%dT%H:%i:%sZ')
ORDER BY eventTime DESC;
-- Access key usage patterns per principal
SELECT userIdentity.arn,
count(*) AS api_call_count,
count(DISTINCT eventName) AS unique_actions,
count(DISTINCT sourceIPAddress) AS unique_ips,
min(eventTime) AS first_seen,
max(eventTime) AS last_seen
FROM cloudtrail_logs
WHERE eventTime > date_format(date_add('day', -30, current_date), '%Y-%m-%dT%H:%i:%sZ')
GROUP BY userIdentity.arn
ORDER BY api_call_count DESC
LIMIT 50;
-- Failed API calls indicating permission issues or reconnaissance
SELECT eventTime, userIdentity.arn, eventName, errorCode, errorMessage,
sourceIPAddress
FROM cloudtrail_logs
WHERE errorCode IN ('AccessDenied', 'UnauthorizedAccess', 'Client.UnauthorizedAccess')
AND eventTime > date_format(date_add('day', -7, current_date), '%Y-%m-%dT%H:%i:%sZ')
ORDER BY eventTime DESC
LIMIT 200;
-- Track KMS key usage
SELECT eventTime, userIdentity.arn, eventName, requestParameters,
resources[1].arn AS key_arn
FROM cloudtrail_logs
WHERE eventSource = 'kms.amazonaws.com'
AND eventName IN ('Decrypt', 'Encrypt', 'GenerateDataKey', 'DisableKey', 'ScheduleKeyDeletion')
AND eventTime > date_format(date_add('day', -7, current_date), '%Y-%m-%dT%H:%i:%sZ')
ORDER BY eventTime DESC;
For production query volumes, register/project all intended partitions and constrain region/year/month/day to prune scan cost; eventTime alone does not prune these partitions. This DDL covers one organization/account prefix, not every member account. Values such as AWS service names or IPv6 addresses need an explicit policy when classifying unusual source IPs.
CloudTrail Lake (Existing Eligible Customers Only)
CloudTrail Lake closed to new customers on May 31, 2026. Verify existing eligibility and organization/account event-store coverage before using this optional example; new customers should choose a supported CloudWatch or S3/Athena design. Trails remain supported. See AWS availability change.
# Create an event data store for long-term queryable storage
aws cloudtrail create-event-data-store \
--name org-audit-event-store \
--multi-region-enabled \
--organization-enabled \
--retention-period 2555 \
--advanced-event-selectors '[
{
"Name": "AllManagementEvents",
"FieldSelectors": [
{"Field": "eventCategory", "Equals": ["Management"]}
]
}
]'
-- CloudTrail Lake SQL queries (run in console or via StartQuery API)
-- Investigate a specific user's activity
SELECT eventTime, eventName, eventSource, sourceIPAddress,
errorCode, requestParameters
FROM EVENT_DATA_STORE_ID
WHERE userIdentity.arn = 'arn:aws:iam::123456789012:user/suspicious-user'
AND eventTime > '2024-01-01 00:00:00'
ORDER BY eventTime DESC;
-- Cross-account activity summary
SELECT recipientAccountId, userIdentity.arn,
count(*) AS event_count
FROM EVENT_DATA_STORE_ID
WHERE eventTime > '2024-01-01 00:00:00'
GROUP BY recipientAccountId, userIdentity.arn
ORDER BY event_count DESC;
Validate Trail Integrity
# Validate log file integrity for a date range
aws cloudtrail validate-logs \
--trail-arn arn:aws:cloudtrail:us-east-1:123456789012:trail/org-audit-trail \
--start-time "2024-01-01T00:00:00Z" \
--end-time "2024-01-31T23:59:59Z"
# Check trail status
aws cloudtrail get-trail-status --name org-audit-trail
# Describe the trail configuration
aws cloudtrail describe-trails --trail-name-list org-audit-trail
Terraform Configuration
resource "aws_cloudtrail" "org_trail" {
name = "org-audit-trail"
s3_bucket_name = aws_s3_bucket.cloudtrail.id
is_organization_trail = true
is_multi_region_trail = true
enable_log_file_validation = true
kms_key_id = aws_kms_key.cloudtrail.arn
cloud_watch_logs_group_arn = "${aws_cloudwatch_log_group.cloudtrail.arn}:*"
cloud_watch_logs_role_arn = aws_iam_role.cloudtrail_cw.arn
include_global_service_events = true
advanced_event_selector {
name = "AllManagementEvents"
field_selector {
field = "eventCategory"
equals = ["Management"]
}
}
advanced_event_selector {
name = "SensitiveS3DataEvents"
field_selector {
field = "eventCategory"
equals = ["Data"]
}
field_selector {
field = "resources.type"
equals = ["AWS::S3::Object"]
}
field_selector {
field = "resources.ARN"
starts_with = ["arn:aws:s3:::sensitive-data-bucket/"]
}
}
tags = {
Environment = "production"
Compliance = "soc2,hipaa"
}
}
The Terraform fragment references externally defined bucket/key/log-role resources and policies; it is not standalone. Plan and inspect changes before applying. For an organization-wide rollout, verify representative member-account/region delivery and CloudWatch access as well as the management account. A metric filter without an alarm does not notify anyone; the example only creates two alarms and the remaining checklist alarms must be implemented and tested separately.
Setup Checklist
cloudtrail_checklist:
trail_configuration:
- "Organization trail enabled across all accounts"
- "Multi-region trail enabled"
- "Log file validation enabled"
- "KMS encryption configured with dedicated key"
- "CloudWatch Logs integration active"
- "S3 bucket policy restricts access to CloudTrail service only"
s3_bucket_hardening:
- "Public access blocked"
- "Versioning enabled"
- "Server-side encryption enabled"
- "Lifecycle policy set for retention and archival"
- "Access logging enabled on the bucket itself"
- "Object Lock enabled for WORM compliance (if required)"
monitoring_and_alerting:
- "Metric filters for unauthorized API calls"
- "Alarm on root account usage"
- "Alarm on console login without MFA"
- "Alarm on IAM policy changes"
- "Alarm on security group and NACL changes"
- "Alarm on CloudTrail configuration changes"
- "Alarm on S3 bucket policy changes"
analysis:
- "Athena table created for ad-hoc queries"
- "CloudTrail Lake event data store for long-term queries"
- "Regular review of high-risk API patterns"
- "Automated reports for compliance evidence"
operational:
- "Trail status health check automated"
- "Log delivery latency monitored"
- "Log file validation run periodically"
- "SNS notification for trail configuration changes"
Verification
After the authorized change, inspect get-trail-status for delivery errors and delivered object/digest timestamps. Use a harmless authorized management event in a test account, find its event ID in S3 and the selected query system, and test alarm routing without disclosing sensitive log bodies. Retain the before/after configuration and unresolved regions/accounts. Compliance tags and a green trail status do not establish complete event coverage or certification.
Best Practices
- Enable organization-wide trails from the management account for full coverage
- Always enable log file validation to detect tampering
- Encrypt logs with a customer-managed KMS key and restrict key usage
- Use advanced event selectors to capture data events on sensitive resources without logging everything
- Integrate with CloudWatch Logs for real-time metric filters and alarms
- Set up Athena or CloudTrail Lake for efficient querying during investigations
- Apply S3 lifecycle policies to transition old logs to Glacier and enforce retention
- Monitor the trail itself (delivery errors, configuration changes) as a meta-control
- Validate log integrity periodically as part of compliance evidence collection
- Restrict access to the CloudTrail S3 bucket and KMS key with least-privilege IAM policies
Limitations
- Guidance and checklists only; not legal advice and not a substitute for a qualified auditor.
- Docs-only import: upstream templates and scripts not bundled.
Example
Map this skill's control checklist to our current evidence and list gaps.
Adapted from BagelHole/DevOps-Security-Agent-Skills (MIT); frontmatter, When to Use/Limitations, and safety boundaries added for upstream compliance. Docs-only import: helper scripts and templates not bundled.
AWS IAM
Manage identity and access in AWS with least-privilege policies, roles, federation, and permission boundaries.
When to Use This Skill
- Creating roles for EC2 instances, Lambda functions, or ECS tasks
- Writing custom IAM policies with least-privilege access
- Setting up OIDC federation for GitHub Actions or other CI/CD systems
- Implementing permission boundaries for delegated administration
- Auditing access with IAM Access Analyzer and credential reports
- Configuring cross-account access with assume-role patterns
- Enforcing MFA and session policies
Prerequisites
- AWS CLI v2 installed and configured
- Least-privilege IAM actions for the chosen roles/policies; iam:* is not a prerequisite
- For OIDC: ability to create identity providers (
iam:CreateOpenIDConnectProvider) - AWS Organizations access for Service Control Policies (SCPs)
IAM Policy Structure
Every IAM policy follows the same JSON structure. Always specify the minimum actions and resources required.
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowS3ReadWrite",
"Effect": "Allow",
"Action": [
"s3:GetObject",
"s3:PutObject",
"s3:ListBucket"
],
"Resource": [
"arn:aws:s3:::my-app-bucket",
"arn:aws:s3:::my-app-bucket/*"
]
},
{
"Sid": "DenyUnencryptedUploads",
"Effect": "Deny",
"Action": "s3:PutObject",
"Resource": "arn:aws:s3:::my-app-bucket/*",
"Condition": {
"StringNotEquals": {
"s3:x-amz-server-side-encryption": "aws:kms"
}
}
}
]
}
Create and Manage Roles
# Create an EC2 instance role with trust policy
aws iam create-role \
--role-name EC2AppRole \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}' \
--tags '[{"Key":"Team","Value":"platform"},{"Key":"Environment","Value":"production"}]'
# Create and attach an inline policy
aws iam put-role-policy \
--role-name EC2AppRole \
--policy-name s3-access \
--policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["s3:GetObject", "s3:PutObject"],
"Resource": "arn:aws:s3:::my-app-bucket/*"
}]
}'
# Attach a managed policy
aws iam attach-role-policy \
--role-name EC2AppRole \
--policy-arn arn:aws:iam::aws:policy/CloudWatchAgentServerPolicy
# Create instance profile and associate the role
aws iam create-instance-profile --instance-profile-name EC2AppProfile
aws iam add-role-to-instance-profile \
--instance-profile-name EC2AppProfile \
--role-name EC2AppRole
# Create a Lambda execution role
aws iam create-role \
--role-name LambdaExecRole \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "lambda.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}'
aws iam attach-role-policy \
--role-name LambdaExecRole \
--policy-arn arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole
Cross-Account Access
# In Account B: create role that Account A can assume
aws iam create-role \
--role-name CrossAccountReadRole \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"AWS": "arn:aws:iam::111111111111:root"},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {"sts:ExternalId": "unique-external-id-12345"}
}
}]
}'
# In Account A: assume the role
aws sts assume-role \
--role-arn arn:aws:iam::222222222222:role/CrossAccountReadRole \
--role-session-name cross-account-session \
--external-id unique-external-id-12345
# Use the temporary credentials
export AWS_ACCESS_KEY_ID="ASIAXXX"
export AWS_SECRET_ACCESS_KEY="xxx"
export AWS_SESSION_TOKEN="xxx"
OIDC Federation for GitHub Actions
# Create the GitHub OIDC identity provider
aws iam create-open-id-connect-provider \
--url https://token.actions.githubusercontent.com \
--client-id-list sts.amazonaws.com \
--thumbprint-list "6938fd4d98bab03faadb97b34396831e3780aea1"
# Create a role for GitHub Actions with repo-scoped trust
aws iam create-role \
--role-name GitHubActionsDeployRole \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {
"Federated": "arn:aws:iam::123456789012:oidc-provider/token.actions.githubusercontent.com"
},
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
},
"StringLike": {
"token.actions.githubusercontent.com:sub": "repo:my-org/my-repo:ref:refs/heads/main"
}
}
}]
}'
# Attach deployment permissions to the role
aws iam attach-role-policy \
--role-name GitHubActionsDeployRole \
--policy-arn arn:aws:iam::123456789012:policy/DeploymentPolicy
GitHub Actions workflow usage:
# .github/workflows/deploy.yml
permissions:
id-token: write
contents: read
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: arn:aws:iam::123456789012:role/GitHubActionsDeployRole
aws-region: us-east-1
- run: aws sts get-caller-identity
Permission Boundaries
# Create a permission boundary policy
aws iam create-policy \
--policy-name DeveloperBoundary \
--policy-document '{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowedServices",
"Effect": "Allow",
"Action": [
"s3:*",
"lambda:*",
"dynamodb:*",
"sqs:*",
"sns:*",
"logs:*",
"cloudwatch:*",
"ecr:*",
"ecs:*"
],
"Resource": "*"
},
{
"Sid": "DenyIAMChanges",
"Effect": "Deny",
"Action": [
"iam:CreateUser",
"iam:DeleteUser",
"iam:CreateRole",
"iam:DeleteRole",
"iam:AttachRolePolicy",
"iam:PutRolePermissionsBoundary",
"iam:DeleteRolePermissionsBoundary"
],
"Resource": "*"
},
{
"Sid": "DenyOutsideRegion",
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"aws:RequestedRegion": ["us-east-1", "us-west-2"]
},
"ArnNotLike": {
"aws:PrincipalArn": "arn:aws:iam::*:role/admin-*"
}
}
}
]
}'
# Create a role with the permission boundary
aws iam create-role \
--role-name DeveloperRole \
--assume-role-policy-document file://trust-policy.json \
--permissions-boundary "arn:aws:iam::123456789012:policy/DeveloperBoundary"
IAM Access Analyzer and Auditing
# Create an IAM Access Analyzer
aws accessanalyzer create-analyzer \
--analyzer-name account-analyzer \
--type ACCOUNT
# List findings (externally accessible resources)
aws accessanalyzer list-findings \
--analyzer-arn arn:aws:access-analyzer:us-east-1:123456789012:analyzer/account-analyzer
# Generate credential report
aws iam generate-credential-report
aws iam get-credential-report --output text --query Content | base64 -d > credential-report.csv
# List IAM users with no IAM MFA device (does not establish console access)
aws iam list-users --query "Users[].UserName" --output text | tr '\t' '\n' | while IFS= read -r user; do
mfa=$(aws iam list-mfa-devices --user-name "$user" --query "MFADevices" --output text)
if [ -z "$mfa" ]; then
echo "NO MFA: $user"
fi
done
# List all policies attached to a role
aws iam list-attached-role-policies --role-name EC2AppRole
aws iam list-role-policies --role-name EC2AppRole
# Get the last-accessed services for a role
aws iam generate-service-last-accessed-details --arn arn:aws:iam::123456789012:role/EC2AppRole
# Then retrieve results with the returned JobId
aws iam get-service-last-accessed-details --job-id "job-id-from-above"
# Simulate a policy to test access
aws iam simulate-principal-policy \
--policy-source-arn arn:aws:iam::123456789012:role/EC2AppRole \
--action-names s3:GetObject s3:PutObject \
--resource-arns arn:aws:s3:::my-app-bucket/data.json
Terraform IAM Role with OIDC
# OIDC provider for GitHub Actions
resource "aws_iam_openid_connect_provider" "github" {
url = "https://token.actions.githubusercontent.com"
client_id_list = ["sts.amazonaws.com"]
thumbprint_list = ["6938fd4d98bab03faadb97b34396831e3780aea1"]
}
# Role for GitHub Actions
resource "aws_iam_role" "github_actions" {
name = "GitHubActionsDeployRole"
assume_role_policy = jsonencode({
Version = "2012-10-17"
Statement = [{
Effect = "Allow"
Principal = {
Federated = aws_iam_openid_connect_provider.github.arn
}
Action = "sts:AssumeRoleWithWebIdentity"
Condition = {
StringEquals = {
"token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
}
StringLike = {
"token.actions.githubusercontent.com:sub" = "repo:my-org/my-repo:ref:refs/heads/main"
}
}
}]
})
permissions_boundary = aws_iam_policy.boundary.arn
}
resource "aws_iam_role_policy_attachment" "deploy" {
role = aws_iam_role.github_actions.name
policy_arn = aws_iam_policy.deployment.arn
}
# Permission boundary
resource "aws_iam_policy" "boundary" {
name = "DeveloperBoundary"
policy = jsonencode({
Version = "2012-10-17"
Statement = [
{
Sid = "AllowedServices"
Effect = "Allow"
Action = ["s3:*", "lambda:*", "dynamodb:*", "ecs:*", "logs:*"]
Resource = "*"
},
{
Sid = "DenyIAMEscalation"
Effect = "Deny"
Action = ["iam:CreateUser", "iam:CreateRole", "iam:AttachRolePolicy"]
Resource = "*"
}
]
})
}
Service Control Policies (Organizations)
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyRootAccount",
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {
"StringLike": {
"aws:PrincipalArn": "arn:aws:iam::*:root"
}
}
},
{
"Sid": "RequireIMDSv2",
"Effect": "Deny",
"Action": "ec2:RunInstances",
"Resource": "arn:aws:ec2:*:*:instance/*",
"Condition": {
"StringNotEquals": {
"ec2:MetadataHttpTokens": "required"
}
}
},
{
"Sid": "DenyRegionsOutsideUS",
"Effect": "Deny",
"Action": "*",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"aws:RequestedRegion": ["us-east-1", "us-west-2"]
},
"ArnNotLike": {
"aws:PrincipalArn": ["arn:aws:iam::*:role/OrganizationAdmin"]
}
}
}
]
}
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| Access Denied on API call | Missing or incorrect policy | Use simulate-principal-policy to test; check resource ARN format |
| Role cannot be assumed | Trust policy does not include the caller | Verify Principal in trust policy matches caller ARN |
| OIDC federation fails | Thumbprint or audience mismatch | Verify OIDC provider URL, client ID list, and condition keys |
| Permission boundary blocks action | Boundary does not include the action | Add the action to the boundary; effective = identity AND boundary |
| Credential report shows stale keys | Keys not rotated in 90+ days | Rotate keys; disable unused access keys |
| Service-linked role creation fails | Organization SCP blocks iam:CreateServiceLinkedRole | Add exception in SCP for the specific service |
| Cross-account assume role fails | Missing ExternalId or wrong account | Verify ExternalId matches; check account number in Principal |
| MFA condition not enforced | Condition key not in policy | Add aws:MultiFactorAuthPresent condition |
Related Skills
- terraform-aws (
terraform-aws) - IaC deployment of IAM resources - aws-ec2 (
aws-ec2) - Instance profiles and roles - aws-lambda (
aws-lambda) - Lambda execution roles - aws-ecs-fargate (
aws-ecs-fargate) - ECS task and execution roles - access-review (
access-review) - Access auditing and governance
Limitations
- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
- Docs-only import: upstream scripts and templates not bundled.
The upload encryption deny above deliberately requires an explicit KMS request header; bucket default encryption alone will not satisfy it. Separate KMS key policy/grants may be required. Account-root trust delegates to permitted identities in that account, not only its root user; narrow to intended role principals. OIDC subject claims must match the intended branch or protected environment, with current provider trust configuration. Region-deny examples can block global services: design tested service exceptions and recovery access before attachment. Boundaries/SCPs do not grant access and are not complete escalation prevention; resource policies, role sessions, PassRole and service-linked roles need separate review. MFA report/90-day heuristics are leads, not proof of credential compromise or console access. Never print temporary credential values into logs; prefer credential-process/profiles. Simulators do not reproduce every real resource-policy/SCP context.
AWS Lambda
Build serverless applications with AWS Lambda, covering function creation, event sources, layers, SAM templates, and cold start optimization.
When to Use This Skill
- Building event-driven applications triggered by API Gateway, S3, SQS, or EventBridge
- Running scheduled tasks (cron) without managing servers
- Processing data streams from Kinesis or DynamoDB
- Building lightweight APIs with API Gateway or function URLs
- Implementing webhooks, Slack bots, or automation scripts
- Reducing compute costs for intermittent or bursty workloads
Prerequisites
- AWS CLI v2 installed and configured
- Least-privilege IAM actions for the chosen resources; restrict
iam:PassRoleto the execution role. Wildcard service grants are not a prerequisite. - Python 3.11+, Node.js 20+, or another supported runtime installed locally
- (Optional) AWS SAM CLI for local development and deployment
Create and Deploy a Function
# Create a deployment package
cd my-function
zip -r function.zip app.py
# Create the Lambda function
aws lambda create-function \
--function-name my-api-handler \
--runtime python3.12 \
--handler app.handler \
--role arn:aws:iam::123456789012:role/LambdaExecRole \
--zip-file fileb://function.zip \
--memory-size 256 \
--timeout 30 \
--environment 'Variables={STAGE=production,LOG_LEVEL=INFO}' \
--architectures arm64 \
--tracing-config Mode=Active \
--tags '{"Team":"backend","Environment":"production"}'
# Update function code
aws lambda update-function-code \
--function-name my-api-handler \
--zip-file fileb://function.zip
# Update function configuration
aws lambda update-function-configuration \
--function-name my-api-handler \
--memory-size 512 \
--timeout 60 \
--environment 'Variables={STAGE=production,LOG_LEVEL=WARNING}'
# Publish a version (immutable snapshot)
aws lambda publish-version \
--function-name my-api-handler \
--description "v1.2.0 - added rate limiting"
# Create an alias pointing to the version
aws lambda create-alias \
--function-name my-api-handler \
--name live \
--function-version 3
# Weighted alias for canary deployments (90% v3, 10% v4)
aws lambda update-alias \
--function-name my-api-handler \
--name live \
--function-version 4 \
--routing-config '{"AdditionalVersionWeights":{"3":0.9}}'
Function Code Examples
# app.py - API Gateway REST proxy (v1) sketch; not the function URL/v2 event shape
import json
import logging
import os
logger = logging.getLogger()
logger.setLevel(os.environ.get("LOG_LEVEL", "INFO"))
def handler(event, context):
"""Handle API Gateway proxy event."""
logger.info("Request: %s %s", event["httpMethod"], event["path"])
try:
body = json.loads(event.get("body") or "{}")
result = process_request(body)
return {
"statusCode": 200,
"headers": {
"Content-Type": "application/json",
"X-Request-Id": context.aws_request_id
},
"body": json.dumps(result)
}
except ValueError as e:
logger.warning("Validation error: %s", e)
return {"statusCode": 400, "body": json.dumps({"error": str(e)})}
except Exception as e:
logger.exception("Unhandled error")
return {"statusCode": 500, "body": json.dumps({"error": "Internal server error"})}
def process_request(body):
return {"message": "OK", "data": body}
# sqs_processor.py - SQS batch processor with partial failure reporting
import json
import logging
logger = logging.getLogger()
logger.setLevel("INFO")
def handler(event, context):
"""Process SQS messages with partial batch failure reporting."""
failed_ids = []
for record in event["Records"]:
try:
body = json.loads(record["body"])
logger.info("Processing message: %s", record["messageId"])
process_message(body)
except Exception as e:
logger.error("Failed message %s: %s", record["messageId"], e)
failed_ids.append(record["messageId"])
# Return failed items so only those get retried
return {
"batchItemFailures": [
{"itemIdentifier": msg_id} for msg_id in failed_ids
]
}
def process_message(body):
pass # your logic here
Lambda Layers
# Build a layer for Python dependencies
mkdir -p layer/python
pip install requests boto3-stubs -t layer/python/
cd layer
zip -r ../my-layer.zip python/
# Publish the layer
aws lambda publish-layer-version \
--layer-name common-deps \
--description "Shared Python dependencies" \
--zip-file fileb://my-layer.zip \
--compatible-runtimes python3.11 python3.12 \
--compatible-architectures arm64 x86_64
# Attach layer to a function
aws lambda update-function-configuration \
--function-name my-api-handler \
--layers "arn:aws:lambda:us-east-1:123456789012:layer:common-deps:1"
# List available layers
aws lambda list-layers --compatible-runtime python3.12
Event Source Mappings
# SQS trigger with batch processing
aws lambda create-event-source-mapping \
--function-name sqs-processor \
--event-source-arn arn:aws:sqs:us-east-1:123456789012:my-queue \
--batch-size 10 \
--maximum-batching-window-in-seconds 5 \
--function-response-types ReportBatchItemFailures
# DynamoDB Streams trigger
aws lambda create-event-source-mapping \
--function-name stream-processor \
--event-source-arn arn:aws:dynamodb:us-east-1:123456789012:table/my-table/stream/2026-01-01T00:00:00.000 \
--batch-size 100 \
--starting-position LATEST \
--maximum-retry-attempts 3 \
--bisect-batch-on-function-error \
--destination-config '{"OnFailure":{"Destination":"arn:aws:sqs:us-east-1:123456789012:dlq"}}'
# S3 event notification (via Lambda permission + S3 config)
aws lambda add-permission \
--function-name image-processor \
--statement-id s3-trigger \
--action lambda:InvokeFunction \
--principal s3.amazonaws.com \
--source-arn arn:aws:s3:::my-uploads-bucket \
--source-account 123456789012
aws s3api put-bucket-notification-configuration \
--bucket my-uploads-bucket \
--notification-configuration '{
"LambdaFunctionConfigurations": [{
"LambdaFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:image-processor",
"Events": ["s3:ObjectCreated:*"],
"Filter": {"Key": {"FilterRules": [{"Name": "suffix", "Value": ".jpg"}]}}
}]
}'
# Schedule with EventBridge (cron)
aws events put-rule \
--name daily-cleanup \
--schedule-expression "cron(0 2 * * ? *)" \
--state ENABLED
aws lambda add-permission \
--function-name daily-cleanup \
--statement-id eventbridge \
--action lambda:InvokeFunction \
--principal events.amazonaws.com \
--source-arn arn:aws:events:us-east-1:123456789012:rule/daily-cleanup
aws events put-targets \
--rule daily-cleanup \
--targets '[{"Id":"1","Arn":"arn:aws:lambda:us-east-1:123456789012:function:daily-cleanup"}]'
Function URLs (No API Gateway Needed)
# Public access requires explicit authorization; CORS is not authentication.
# Prefer AWS_IAM for private endpoints. Create public URL only when requested.
aws lambda create-function-url-config \
--function-name my-api-handler \
--auth-type NONE \
--cors '{
"AllowOrigins": ["https://myapp.com"],
"AllowMethods": ["GET", "POST"],
"AllowHeaders": ["Content-Type"],
"MaxAge": 86400
}'
# Grant public invoke for function URL
aws lambda add-permission \
--function-name my-api-handler \
--statement-id function-url-public \
--action lambda:InvokeFunctionUrl \
--principal "*" \
--function-url-auth-type NONE
aws lambda add-permission \
--function-name my-api-handler \
--statement-id function-url-public-invoke \
--action lambda:InvokeFunction \
--principal "*" \
--invoked-via-function-url
Cold Start Optimization
# Provision capacity to reduce cold starts within provisioned concurrency; spillover may initialize
aws lambda put-provisioned-concurrency-config \
--function-name my-api-handler \
--qualifier live \
--provisioned-concurrent-executions 10
# Set reserved concurrency (throttle limit)
aws lambda put-function-concurrency \
--function-name my-api-handler \
--reserved-concurrent-executions 100
# Enable SnapStart for Java functions (near-zero cold starts)
aws lambda update-function-configuration \
--function-name my-java-handler \
--snap-start '{"ApplyOn": "PublishedVersions"}'
aws lambda publish-version --function-name my-java-handler
Cold start reduction tips:
- Benchmark supported architectures; verify native dependency compatibility and regional pricing
- Minimize deployment package size; use layers for large dependencies
- Initialize SDK clients outside the handler function
- Avoid VPC unless required (VPC cold starts are longer)
- Use provisioned concurrency for latency-sensitive paths
SAM Template
# template.yaml - AWS SAM application
AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: My serverless API
Globals:
Function:
Runtime: python3.12
Architectures: [arm64]
MemorySize: 256
Timeout: 30
Tracing: Active
Environment:
Variables:
STAGE: !Ref Stage
LOG_LEVEL: INFO
Parameters:
Stage:
Type: String
Default: dev
AllowedValues: [dev, staging, prod]
Resources:
ApiFunction:
Type: AWS::Serverless::Function
Properties:
FunctionName: !Sub "${Stage}-api-handler"
Handler: app.handler
CodeUri: src/
Layers:
- !Ref DepsLayer
Events:
GetItems:
Type: Api
Properties:
Path: /items
Method: get
PostItem:
Type: Api
Properties:
Path: /items
Method: post
Policies:
- DynamoDBCrudPolicy:
TableName: !Ref ItemsTable
QueueProcessor:
Type: AWS::Serverless::Function
Properties:
FunctionName: !Sub "${Stage}-queue-processor"
Handler: sqs_processor.handler
CodeUri: src/
Events:
SQSEvent:
Type: SQS
Properties:
Queue: !GetAtt ProcessingQueue.Arn
BatchSize: 10
FunctionResponseTypes:
- ReportBatchItemFailures
DepsLayer:
Type: AWS::Serverless::LayerVersion
Properties:
LayerName: common-deps
ContentUri: layer/
CompatibleRuntimes:
- python3.12
ItemsTable:
Type: AWS::DynamoDB::Table
Properties:
TableName: !Sub "${Stage}-items"
BillingMode: PAY_PER_REQUEST
AttributeDefinitions:
- AttributeName: id
AttributeType: S
KeySchema:
- AttributeName: id
KeyType: HASH
ProcessingQueue:
Type: AWS::SQS::Queue
Properties:
QueueName: !Sub "${Stage}-processing"
VisibilityTimeout: 360
Outputs:
ApiEndpoint:
Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod"
# SAM CLI commands
sam build
sam local invoke ApiFunction --event events/get-items.json
sam local start-api --port 3000
sam deploy --guided
sam logs --name ApiFunction --stack-name my-stack --tail
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| Function times out | Timeout too low or downstream slow | Increase timeout; check VPC/NAT config |
| Out of memory | Memory limit too small | Increase --memory-size; profile with CloudWatch Insights |
| Permission denied on AWS API | Execution role missing policy | Attach required policy to the execution role |
| Cold starts > 5s | Large package or VPC overhead | Use layers, arm64, provisioned concurrency; remove VPC if not needed |
| SQS messages reprocessed | Visibility timeout < function timeout | Use at least six times the function timeout plus batching window; also implement idempotency |
| Event source mapping disabled | Too many consecutive errors | Fix the function error; re-enable the mapping |
| Layer not found | Wrong region or deleted version | Verify layer ARN region matches function region |
| Canary deployment not shifting | Alias routing config wrong | Verify version numbers in routing config |
| Cannot invoke function URL | Missing resource-based policy | Check both URL and function invoke permissions |
Related Skills
- aws-iam (
aws-iam) - Execution roles and permissions - terraform-aws (
terraform-aws) - IaC deployment for Lambda - aws-s3 (
aws-s3) - S3 event triggers - aws-vpc (
aws-vpc) - VPC configuration for Lambda - aws-cost-optimization (
aws-cost-optimization) - Optimizing Lambda spend
Limitations
- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
- Docs-only import: upstream scripts and templates not bundled.
Environment, layer and S3 notification configuration commands replace the corresponding full configuration; read and merge existing settings first. Build native dependencies for the selected Linux runtime and architecture. The SQS example assumes a standard queue; FIFO partial failures must stop at the first failure and include unprocessed records to preserve order. All retryable handlers need idempotent side effects. Provisioned concurrency and public invocation incur costs. Function URL authorization requires both invoke permissions for new URLs since October 2025.
AWS MCP Server Configuration Guide
When to Use
Use this skill when you need configure AWS MCP servers for documentation search and API access. Use when setting up AWS MCP, configuring AWS documentation tools, troubleshooting MCP connectivity, or when user mentions aws-mcp, awsdocs, uvx setup, or MCP server configuration. Covers both Full AWS MCP Server (with...
Overview
This guide helps you configure AWS MCP tools for AI agents. Two options are available:
| Option | Requirements | Capabilities |
|---|---|---|
| Full AWS MCP Server | Python 3.10+, uvx, AWS credentials | Execute AWS API calls + documentation search |
| AWS Documentation MCP | None | Documentation search only |
Step 1: Check Existing Configuration
Before configuring, check if AWS MCP tools are already available using either method:
Method A: Check Available Tools (Recommended)
Look for these tool name patterns in your agent's available tools:
mcp__aws-mcp__*ormcp__aws__*→ Full AWS MCP Server configuredmcp__*awsdocs*__aws___*→ AWS Documentation MCP configured
How to check: Run /mcp command to list all active MCP servers.
Method B: Check Configuration Files
The table is a Claude-oriented example; actual file locations and precedence depend on the client and managed policy. Inspect supported configuration rather than assuming this order:
| Scope | File Location | Use Case |
|---|---|---|
| Local | .claude.json (in project) | Personal/experimental |
| Project | .mcp.json (project root) | Team-shared |
| User | ~/.claude.json | Cross-project personal |
| Enterprise | System managed directories | Organization-wide |
Check these files for mcpServers containing aws-mcp, aws, or awsdocs keys:
# Check project config
cat .mcp.json 2>/dev/null | grep -E '"(aws-mcp|aws|awsdocs)"'
# Check user config
cat ~/.claude.json 2>/dev/null | grep -E '"(aws-mcp|aws|awsdocs)"'
# Or use Claude CLI
claude mcp list
If AWS MCP is already configured, no further setup needed.
Inspect configuration structurally and redact env/header values; do not print credential-bearing lines from minified config. Preserve existing server entries and validate the exact account/region/client config before editing. Prefer documentation-only access for documentation requests, otherwise read-only scoped IAM/tool mode; write-capable actions require separate authorized scope. Use the current downstream-service IAM model; do not copy retired preview MCP actions. Pin/review the proxy and dependencies before execution.
Step 2: Choose Configuration Method
Automatic Detection
Run these commands to determine which option to use:
# Check for uvx (requires Python 3.10+)
which uvx || echo "uvx not available"
# Check for valid AWS credentials
aws sts get-caller-identity || echo "AWS credentials not configured"
Option A: Full AWS MCP Server (only when API access is needed)
Use when: uvx available AND AWS credentials valid
Prerequisites:
- Python 3.10+ with
uvpackage manager - AWS credentials configured (via profile, environment variables, or IAM role)
IAM permissions: Current AWS MCP forwards the caller's credentials to downstream AWS services. Grant only the actual service actions/resources required by the task. Preview-era aws-mcp:InvokeMcp/CallReadOnlyTool/CallReadWriteTool actions no longer grant or deny access. Use current AWS IAM guidance and MCP condition keys where needed; do not treat a client read-only flag as an IAM boundary.
Configuration (add to your MCP settings):
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws@<reviewed-version>",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
Credential Configuration Options:
-
AWS Profile (recommended for development):
"args": [ "mcp-proxy-for-aws@<reviewed-version>", "https://aws-mcp.us-east-1.api.aws/mcp", "--profile", "my-profile", "--metadata", "AWS_REGION=us-west-2" ] -
Environment Variables:
"env": { "AWS_ACCESS_KEY_ID": "...", "AWS_SECRET_ACCESS_KEY": "...", "AWS_REGION": "us-west-2" } -
IAM Role (for EC2/ECS/Lambda): No additional config needed - uses instance credentials
Additional Options:
--region <region>: Override AWS region--read-only: Restrict to read-only tools--log-level <level>: Set logging level (debug, info, warning, error)
Reference: https://github.com/aws/mcp-proxy-for-aws
Option B: AWS Documentation MCP Server (No Auth)
Use when:
- No Python/uvx environment
- No AWS credentials
- Only need documentation search (no API execution)
Configuration:
{
"mcpServers": {
"awsdocs": {
"type": "http",
"url": "https://knowledge-mcp.global.api.aws"
}
}
}
Step 3: Verification
After configuration, verify tools are available:
For Full AWS MCP:
- Look for tools:
mcp__aws-mcp__aws___search_documentation,mcp__aws-mcp__aws___call_aws
For Documentation MCP:
- Look for tools:
mcp__awsdocs__aws___search_documentation,mcp__awsdocs__aws___read_documentation
Troubleshooting
| Issue | Cause | Solution |
|---|---|---|
uvx: command not found | uv not installed | Install with pip install uv or use Option B |
AccessDenied error | Missing IAM permissions | Identify the exact denied action/resource and add only reviewed least-privilege permissions; never fix with aws-mcp:* |
InvalidSignatureException | Credential issue | Check aws sts get-caller-identity |
| Tools not appearing | MCP not started | Restart your agent after config change |
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
AWS Serverless
Specialized skill for building production-ready serverless applications on AWS. Covers Lambda functions, API Gateway, DynamoDB, SQS/SNS event-driven patterns, SAM/CDK deployment, and cold start optimization.
Detailed Guide
Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
Scope and validation
Before deployment confirm account/region, IAM scope, resource changes, data retention and budget. Review the synthesized template/change set and verify in a scoped development environment. Bundled material is documentation only; helper handlers and deployment files shown in snippets are not present or runtime-tested here. Secrets need approved managed storage and least-privilege roles; do not paste credentials into logs.
Monitor memory usage
exports.handler = async (event, context) => {
const used = process.memoryUsage();
console.log('Memory:', {
heapUsed: Math.round(used.heapUsed / 1024 / 1024) + 'MB',
heapTotal: Math.round(used.heapTotal / 1024 / 1024) + 'MB'
});
// ...
};
When to Use
Use this skill when the request clearly matches the capabilities and patterns described above.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
AWS Skill Collection Workflow
When to Use
- You need to choose an AWS architecture or infrastructure workflow for an existing application.
- You want to review an infrastructure plan before any cloud change.
Workflow
- Establish the application requirements, existing AWS services, target account/region, constraints, and required outcome. Read the project's infrastructure definitions before proposing changes.
- Open the upstream AWS skill collection and select the workflow matching the actual services and infrastructure framework. This catalog entry is a routing workflow; it does not bundle every upstream skill.
- Read that workflow's prerequisites and referenced documentation. For an existing deployment, request authorized read-only inventory or use user-provided configuration; do not infer account identity from names.
- Produce an architecture or infrastructure plan with resource boundaries, IAM access, networking, cost assumptions, and a validation/rollback plan. Distinguish observed configuration from proposed changes.
- Review the plan with the user before any operation that creates, modifies, or deletes cloud resources. Follow the selected tool's current documentation and the project's normal review/deployment process.
- Verify the result against the requested requirements and report which checks ran, which were simulated, and which require deployment access.
Example
Review this application's AWS infrastructure and propose a least-privilege change plan. Read configuration first; do not deploy.
Limitations
- The upstream collection is an external prerequisite; report inaccessible guidance instead of inventing its instructions.
- Planning does not prove a deployment works. Never claim account, pricing, permissions, or availability without current evidence.
- Cloud changes require the user's authorized scope and the project's deployment controls.
AWS VPC
Design and manage Virtual Private Cloud networking for production AWS environments with proper subnet isolation, routing, and security.
When to Use This Skill
- Building a new VPC for production, staging, or development
- Setting up public/private subnet architecture across multiple AZs
- Configuring NAT Gateways for private subnet internet access
- Creating security groups and NACLs for network segmentation
- Setting up VPC peering or Transit Gateway for multi-VPC connectivity
- Implementing VPC endpoints for private access to AWS services
- Troubleshooting connectivity issues between resources
Prerequisites
- AWS CLI v2 installed and configured
- IAM permissions scoped to the needed VPC actions/resources and approved account/region
- CIDR range planning completed (avoid overlaps with on-premises or other VPCs)
- For VPC peering: access to both VPCs (same or different accounts)
Network Architecture
Diagram address counts are total addresses; AWS reserves five per subnet, so a /24 normally has251 assignable addresses. Confirm account/region, AZ availability, nonoverlapping CIDRs, routing and approved cost before creation. CLI examples create twoAZs; the Terraform example creates three. Inspect existing resources and plan rollback rather than rerunning non-idempotent create commands. VPC/subnet tags do not enforce isolation: explicitly associate data subnets with local-only route tables and verify no inherited default route. New security groups allow all outbound by default; scope egress to actual dependencies.
VPC (10.0.0.0/16) - 65,536 IPs
├── Public Subnets (internet-facing via IGW)
│ ├── 10.0.1.0/24 (us-east-1a) - 256 IPs - ALBs, NAT GW, bastion
│ ├── 10.0.2.0/24 (us-east-1b) - 256 IPs
│ └── 10.0.3.0/24 (us-east-1c) - 256 IPs
├── Private Subnets (app tier, NAT GW for outbound)
│ ├── 10.0.11.0/24 (us-east-1a) - 256 IPs - ECS, EC2, Lambda
│ ├── 10.0.12.0/24 (us-east-1b) - 256 IPs
│ └── 10.0.13.0/24 (us-east-1c) - 256 IPs
├── Data Subnets (isolated, no internet)
│ ├── 10.0.21.0/24 (us-east-1a) - 256 IPs - RDS, ElastiCache
│ ├── 10.0.22.0/24 (us-east-1b) - 256 IPs
│ └── 10.0.23.0/24 (us-east-1c) - 256 IPs
├── Internet Gateway
├── NAT Gateways (one per AZ for HA)
├── Route Tables (public, private, data)
└── VPC Flow Logs → CloudWatch / S3
Create a VPC with CLI
# Create the VPC
VPC_ID=$(aws ec2 create-vpc \
--cidr-block 10.0.0.0/16 \
--tag-specifications 'ResourceType=vpc,Tags=[{Key=Name,Value=production-vpc},{Key=Environment,Value=production}]' \
--query 'Vpc.VpcId' --output text)
# Enable DNS support and hostnames
aws ec2 modify-vpc-attribute --vpc-id $VPC_ID --enable-dns-support '{"Value":true}'
aws ec2 modify-vpc-attribute --vpc-id $VPC_ID --enable-dns-hostnames '{"Value":true}'
# Create public subnets
PUB_SUB_A=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.1.0/24 \
--availability-zone us-east-1a \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=public-a},{Key=Tier,Value=public}]' \
--query 'Subnet.SubnetId' --output text)
PUB_SUB_B=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.2.0/24 \
--availability-zone us-east-1b \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=public-b},{Key=Tier,Value=public}]' \
--query 'Subnet.SubnetId' --output text)
# Enable auto-assign public IP on public subnets
aws ec2 modify-subnet-attribute --subnet-id $PUB_SUB_A --map-public-ip-on-launch
aws ec2 modify-subnet-attribute --subnet-id $PUB_SUB_B --map-public-ip-on-launch
# Create private subnets
PRIV_SUB_A=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.11.0/24 \
--availability-zone us-east-1a \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=private-a},{Key=Tier,Value=private}]' \
--query 'Subnet.SubnetId' --output text)
PRIV_SUB_B=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.12.0/24 \
--availability-zone us-east-1b \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=private-b},{Key=Tier,Value=private}]' \
--query 'Subnet.SubnetId' --output text)
# Create data subnets (isolated)
DATA_SUB_A=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.21.0/24 \
--availability-zone us-east-1a \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=data-a},{Key=Tier,Value=data}]' \
--query 'Subnet.SubnetId' --output text)
DATA_SUB_B=$(aws ec2 create-subnet \
--vpc-id $VPC_ID \
--cidr-block 10.0.22.0/24 \
--availability-zone us-east-1b \
--tag-specifications 'ResourceType=subnet,Tags=[{Key=Name,Value=data-b},{Key=Tier,Value=data}]' \
--query 'Subnet.SubnetId' --output text)
Internet Gateway and NAT Gateway
# Create and attach Internet Gateway
IGW_ID=$(aws ec2 create-internet-gateway \
--tag-specifications 'ResourceType=internet-gateway,Tags=[{Key=Name,Value=production-igw}]' \
--query 'InternetGateway.InternetGatewayId' --output text)
aws ec2 attach-internet-gateway --vpc-id $VPC_ID --internet-gateway-id $IGW_ID
# Create public route table
PUB_RT=$(aws ec2 create-route-table \
--vpc-id $VPC_ID \
--tag-specifications 'ResourceType=route-table,Tags=[{Key=Name,Value=public-rt}]' \
--query 'RouteTable.RouteTableId' --output text)
aws ec2 create-route --route-table-id $PUB_RT --destination-cidr-block 0.0.0.0/0 --gateway-id $IGW_ID
aws ec2 associate-route-table --route-table-id $PUB_RT --subnet-id $PUB_SUB_A
aws ec2 associate-route-table --route-table-id $PUB_RT --subnet-id $PUB_SUB_B
# Allocate Elastic IPs for NAT Gateways (one per AZ for HA)
EIP_A=$(aws ec2 allocate-address --domain vpc --query 'AllocationId' --output text)
EIP_B=$(aws ec2 allocate-address --domain vpc --query 'AllocationId' --output text)
# Create NAT Gateways in public subnets
NAT_A=$(aws ec2 create-nat-gateway \
--subnet-id $PUB_SUB_A \
--allocation-id $EIP_A \
--tag-specifications 'ResourceType=natgateway,Tags=[{Key=Name,Value=nat-a}]' \
--query 'NatGateway.NatGatewayId' --output text)
NAT_B=$(aws ec2 create-nat-gateway \
--subnet-id $PUB_SUB_B \
--allocation-id $EIP_B \
--tag-specifications 'ResourceType=natgateway,Tags=[{Key=Name,Value=nat-b}]' \
--query 'NatGateway.NatGatewayId' --output text)
# Wait for NAT Gateways
aws ec2 wait nat-gateway-available --nat-gateway-ids $NAT_A $NAT_B
# Create private route tables (one per AZ for HA NAT)
PRIV_RT_A=$(aws ec2 create-route-table \
--vpc-id $VPC_ID \
--tag-specifications 'ResourceType=route-table,Tags=[{Key=Name,Value=private-rt-a}]' \
--query 'RouteTable.RouteTableId' --output text)
aws ec2 create-route --route-table-id $PRIV_RT_A --destination-cidr-block 0.0.0.0/0 --nat-gateway-id $NAT_A
aws ec2 associate-route-table --route-table-id $PRIV_RT_A --subnet-id $PRIV_SUB_A
PRIV_RT_B=$(aws ec2 create-route-table \
--vpc-id $VPC_ID \
--tag-specifications 'ResourceType=route-table,Tags=[{Key=Name,Value=private-rt-b}]' \
--query 'RouteTable.RouteTableId' --output text)
aws ec2 create-route --route-table-id $PRIV_RT_B --destination-cidr-block 0.0.0.0/0 --nat-gateway-id $NAT_B
aws ec2 associate-route-table --route-table-id $PRIV_RT_B --subnet-id $PRIV_SUB_B
Security Groups
# ALB security group (public-facing)
ALB_SG=$(aws ec2 create-security-group \
--group-name alb-sg \
--description "Application Load Balancer" \
--vpc-id $VPC_ID \
--query 'GroupId' --output text)
aws ec2 authorize-security-group-ingress --group-id $ALB_SG --protocol tcp --port 443 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id $ALB_SG --protocol tcp --port 80 --cidr 0.0.0.0/0
# Application security group (only from ALB)
APP_SG=$(aws ec2 create-security-group \
--group-name app-sg \
--description "Application tier" \
--vpc-id $VPC_ID \
--query 'GroupId' --output text)
aws ec2 authorize-security-group-ingress \
--group-id $APP_SG \
--protocol tcp \
--port 8080 \
--source-group $ALB_SG
# Database security group (only from app tier)
DB_SG=$(aws ec2 create-security-group \
--group-name db-sg \
--description "Database tier" \
--vpc-id $VPC_ID \
--query 'GroupId' --output text)
aws ec2 authorize-security-group-ingress \
--group-id $DB_SG \
--protocol tcp \
--port 5432 \
--source-group $APP_SG
# List all security groups in the VPC
aws ec2 describe-security-groups \
--filters "Name=vpc-id,Values=$VPC_ID" \
--query "SecurityGroups[].{Name:GroupName,ID:GroupId,Description:Description}" \
--output table
VPC Endpoints (Private Access to AWS Services)
# Gateway endpoint for S3 (free, route-table based)
aws ec2 create-vpc-endpoint \
--vpc-id $VPC_ID \
--service-name com.amazonaws.us-east-1.s3 \
--route-table-ids $PRIV_RT_A $PRIV_RT_B \
--tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=s3-endpoint}]'
# Gateway endpoint for DynamoDB (free)
aws ec2 create-vpc-endpoint \
--vpc-id $VPC_ID \
--service-name com.amazonaws.us-east-1.dynamodb \
--route-table-ids $PRIV_RT_A $PRIV_RT_B
# Create a dedicated endpoint SG: app must reach endpoint443, not app-SG8080 ingress.
ENDPOINT_SG=$(aws ec2 create-security-group --group-name secrets-endpoint-sg \
--description "Secrets Manager endpoint TLS" --vpc-id "$VPC_ID" --query GroupId --output text)
aws ec2 authorize-security-group-ingress --group-id "$ENDPOINT_SG" --protocol tcp --port 443 --source-group "$APP_SG"
# Interface endpoint for Secrets Manager (ENI-based, has hourly cost)
aws ec2 create-vpc-endpoint \
--vpc-id $VPC_ID \
--vpc-endpoint-type Interface \
--service-name com.amazonaws.us-east-1.secretsmanager \
--subnet-ids $PRIV_SUB_A $PRIV_SUB_B \
--security-group-ids "$ENDPOINT_SG" \
--private-dns-enabled \
--tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=secretsmanager-endpoint}]'
VPC Flow Logs
# Enable VPC flow logs to CloudWatch
aws ec2 create-flow-log \
--resource-type VPC \
--resource-ids $VPC_ID \
--traffic-type ALL \
--log-destination-type cloud-watch-logs \
--log-group-name /vpc/production-flow-logs \
--deliver-logs-permission-arn arn:aws:iam::123456789012:role/VPCFlowLogRole \
--max-aggregation-interval 60 \
--tag-specifications 'ResourceType=vpc-flow-log,Tags=[{Key=Name,Value=production-flow-log}]'
# Enable VPC flow logs to S3 (cheaper for long-term storage)
aws ec2 create-flow-log \
--resource-type VPC \
--resource-ids $VPC_ID \
--traffic-type ALL \
--log-destination-type s3 \
--log-destination arn:aws:s3:::my-flow-logs-bucket/vpc-logs/ \
--max-aggregation-interval 60
VPC Peering
# Request peering connection
PEERING_ID=$(aws ec2 create-vpc-peering-connection \
--vpc-id vpc-requester \
--peer-vpc-id vpc-accepter \
--peer-owner-id 987654321098 \
--peer-region us-west-2 \
--tag-specifications 'ResourceType=vpc-peering-connection,Tags=[{Key=Name,Value=prod-to-shared}]' \
--query 'VpcPeeringConnection.VpcPeeringConnectionId' --output text)
# Accept peering (from the accepter account/region)
aws ec2 accept-vpc-peering-connection --vpc-peering-connection-id $PEERING_ID
# Add routes in both VPCs
aws ec2 create-route --route-table-id rtb-requester --destination-cidr-block 10.1.0.0/16 --vpc-peering-connection-id $PEERING_ID
aws ec2 create-route --route-table-id rtb-accepter --destination-cidr-block 10.0.0.0/16 --vpc-peering-connection-id $PEERING_ID
Terraform VPC Module
resource "aws_vpc" "main" {
cidr_block = "10.0.0.0/16"
enable_dns_support = true
enable_dns_hostnames = true
tags = {
Name = "production-vpc"
Environment = "production"
}
}
resource "aws_subnet" "public" {
count = 3
vpc_id = aws_vpc.main.id
cidr_block = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index + 1)
availability_zone = data.aws_availability_zones.available.names[count.index]
map_public_ip_on_launch = true
tags = {
Name = "public-${data.aws_availability_zones.available.names[count.index]}"
Tier = "public"
}
}
resource "aws_subnet" "private" {
count = 3
vpc_id = aws_vpc.main.id
cidr_block = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index + 11)
availability_zone = data.aws_availability_zones.available.names[count.index]
tags = {
Name = "private-${data.aws_availability_zones.available.names[count.index]}"
Tier = "private"
}
}
resource "aws_subnet" "data" {
count = 3
vpc_id = aws_vpc.main.id
cidr_block = cidrsubnet(aws_vpc.main.cidr_block, 8, count.index + 21)
availability_zone = data.aws_availability_zones.available.names[count.index]
tags = {
Name = "data-${data.aws_availability_zones.available.names[count.index]}"
Tier = "data"
}
}
resource "aws_internet_gateway" "main" {
vpc_id = aws_vpc.main.id
tags = { Name = "production-igw" }
}
resource "aws_eip" "nat" {
count = 3
domain = "vpc"
tags = { Name = "nat-eip-${count.index}" }
}
resource "aws_nat_gateway" "main" {
count = 3
allocation_id = aws_eip.nat[count.index].id
subnet_id = aws_subnet.public[count.index].id
tags = { Name = "nat-${count.index}" }
depends_on = [aws_internet_gateway.main]
}
resource "aws_route_table" "public" {
vpc_id = aws_vpc.main.id
route {
cidr_block = "0.0.0.0/0"
gateway_id = aws_internet_gateway.main.id
}
tags = { Name = "public-rt" }
}
resource "aws_route_table_association" "public" {
count = 3
subnet_id = aws_subnet.public[count.index].id
route_table_id = aws_route_table.public.id
}
resource "aws_route_table" "private" {
count = 3
vpc_id = aws_vpc.main.id
route {
cidr_block = "0.0.0.0/0"
nat_gateway_id = aws_nat_gateway.main[count.index].id
}
tags = { Name = "private-rt-${count.index}" }
}
resource "aws_route_table_association" "private" {
count = 3
subnet_id = aws_subnet.private[count.index].id
route_table_id = aws_route_table.private[count.index].id
}
resource "aws_vpc_endpoint" "s3" {
vpc_id = aws_vpc.main.id
service_name = "com.amazonaws.${data.aws_region.current.name}.s3"
route_table_ids = aws_route_table.private[*].id
tags = { Name = "s3-endpoint" }
}
resource "aws_flow_log" "main" {
vpc_id = aws_vpc.main.id
traffic_type = "ALL"
log_destination_type = "s3"
log_destination = "${aws_s3_bucket.flow_logs.arn}/vpc-logs/"
max_aggregation_interval = 60
}
The Terraform fragment also needs provider constraints, aws_availability_zones/aws_region data sources, flow-log bucket policy/retention and explicit isolated data route associations; it is not a standalone module. An S3 gateway endpoint has no endpoint hourly fee, but storage/request/transfer charges can still apply. Peering is non-transitive and needs explicit accepter account/region credentials, security rules and DNS options; it does not permit using a peer’s NAT/IGW. More NAT gateways can reduce cross-AZ traffic but increase hourly cost: evaluate both instead of claiming automatic savings.
Troubleshooting
| Problem | Cause | Fix |
|---|---|---|
| Cannot reach internet from private subnet | NAT Gateway route missing | Add 0.0.0.0/0 route to NAT GW in private route table |
| Cannot reach internet from public subnet | IGW not attached or route missing | Attach IGW; add 0.0.0.0/0 route to IGW in public RT |
| EC2 cannot reach S3 | No VPC endpoint or NAT | Add S3 gateway endpoint (free) or ensure NAT GW route |
| Security group rule not working | Wrong direction (ingress vs egress) | SG is stateful; check inbound rule on destination |
| NACL blocking traffic | NACLs are stateless; need both directions | Add matching inbound AND outbound rules with correct ports |
| VPC peering one-way only | Routes missing in one VPC | Add routes in BOTH VPC route tables |
| DNS resolution failing | DNS hostnames not enabled on VPC | Enable enableDnsHostnames on VPC |
| NAT Gateway charges high | All AZs routing through one NAT | Deploy NAT GW per AZ with separate route tables |
| Cross-AZ data transfer costs | Resources in different AZs communicating | Co-locate tightly coupled services in same AZ |
Related Skills
- aws-ec2 (
aws-ec2) - Instances deployed in VPC subnets - aws-ecs-fargate (
aws-ecs-fargate) - ECS tasks in VPC networking - aws-rds (
aws-rds) - Database subnet groups - terraform-aws (
terraform-aws) - IaC for VPC infrastructure - firewall-config (
firewall-config) - Network security controls
Limitations
- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
- Docs-only import: upstream scripts and templates not bundled.
Azure.AI.Agents.Persistent (.NET)
Low-level SDK for creating and managing persistent AI agents with threads, messages, runs, and tools.
Installation
dotnet add package Azure.AI.Agents.Persistent --prerelease
dotnet add package Azure.Identity
Current Versions: Stable v1.1.0, Preview v1.2.0-beta.8
Environment Variables
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_BING_CONNECTION_ID=<bing-connection-resource-id>
AZURE_AI_SEARCH_CONNECTION_ID=<search-connection-resource-id>
Authentication
using Azure.AI.Agents.Persistent;
using Azure.Identity;
var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());
Client Hierarchy
PersistentAgentsClient
├── Administration → Agent CRUD operations
├── Threads → Thread management
├── Messages → Message operations
├── Runs → Run execution and streaming
├── Files → File upload/download
└── VectorStores → Vector store management
Core Workflow
Pin compatible package versions and verify the linked SDK signatures; fragments use project-defined helper functions and are not a complete application. Confirm endpoint/deployment, authorized tool actions, upload scope and budget before runs. Use a finite cancellation deadline for polling/streaming and distinguish completed, failed, cancelled, expired and requires-action states before reading a final answer. Validate/allowlist each function name and typed argument set before execution; never execute raw model arguments as code or SQL. Delete only resources created by the current run in a finally block, preserving needed evidence.
1. Create Agent
var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
PersistentAgent agent = await client.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "Math Tutor",
instructions: "You are a personal math tutor. Write and run code to answer math questions.",
tools: [new CodeInterpreterToolDefinition()]
);
2. Create Thread and Message
// Create thread
PersistentAgentThread thread = await client.Threads.CreateThreadAsync();
// Create message
await client.Messages.CreateMessageAsync(
thread.Id,
MessageRole.User,
"I need to solve the equation `3x + 11 = 14`. Can you help me?"
);
3. Run Agent (Polling)
// Create run
ThreadRun run = await client.Runs.CreateRunAsync(
thread.Id,
agent.Id,
additionalInstructions: "Please address the user as Jane Doe."
);
// Poll for completion
do
{
await Task.Delay(TimeSpan.FromMilliseconds(500));
run = await client.Runs.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
// Retrieve messages
await foreach (PersistentThreadMessage message in client.Messages.GetMessagesAsync(
threadId: thread.Id,
order: ListSortOrder.Ascending))
{
Console.Write($"{message.Role}: ");
foreach (MessageContent content in message.ContentItems)
{
if (content is MessageTextContent textContent)
Console.WriteLine(textContent.Text);
}
}
4. Streaming Response
AsyncCollectionResult<StreamingUpdate> stream = client.Runs.CreateRunStreamingAsync(
thread.Id,
agent.Id
);
await foreach (StreamingUpdate update in stream)
{
if (update.UpdateKind == StreamingUpdateReason.RunCreated)
{
Console.WriteLine("--- Run started! ---");
}
else if (update is MessageContentUpdate contentUpdate)
{
Console.Write(contentUpdate.Text);
}
else if (update.UpdateKind == StreamingUpdateReason.RunCompleted)
{
Console.WriteLine("\n--- Run completed! ---");
}
}
5. Function Calling
// Define function tool
FunctionToolDefinition weatherTool = new(
name: "getCurrentWeather",
description: "Gets the current weather at a location.",
parameters: BinaryData.FromObjectAsJson(new
{
Type = "object",
Properties = new
{
Location = new { Type = "string", Description = "City and state, e.g. San Francisco, CA" },
Unit = new { Type = "string", Enum = new[] { "c", "f" } }
},
Required = new[] { "location" }
}, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
);
// Create agent with function
PersistentAgent agent = await client.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "Weather Bot",
instructions: "You are a weather bot.",
tools: [weatherTool]
);
// Handle function calls during polling
do
{
await Task.Delay(500);
run = await client.Runs.GetRunAsync(thread.Id, run.Id);
if (run.Status == RunStatus.RequiresAction
&& run.RequiredAction is SubmitToolOutputsAction submitAction)
{
List<ToolOutput> outputs = [];
foreach (RequiredToolCall toolCall in submitAction.ToolCalls)
{
if (toolCall is RequiredFunctionToolCall funcCall)
{
// Execute function and get result
string result = ExecuteFunction(funcCall.Name, funcCall.Arguments);
outputs.Add(new ToolOutput(toolCall, result));
}
}
run = await client.Runs.SubmitToolOutputsToRunAsync(run, outputs, toolApprovals: null);
}
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);
6. File Search with Vector Store
// Upload file
PersistentAgentFileInfo file = await client.Files.UploadFileAsync(
filePath: "document.txt",
purpose: PersistentAgentFilePurpose.Agents
);
// Create vector store
PersistentAgentsVectorStore vectorStore = await client.VectorStores.CreateVectorStoreAsync(
fileIds: [file.Id],
name: "my_vector_store"
);
// Create file search resource
FileSearchToolResource fileSearchResource = new();
fileSearchResource.VectorStoreIds.Add(vectorStore.Id);
// Create agent with file search
PersistentAgent agent = await client.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "Document Assistant",
instructions: "You help users find information in documents.",
tools: [new FileSearchToolDefinition()],
toolResources: new ToolResources { FileSearch = fileSearchResource }
);
7. Bing Grounding
var bingConnectionId = Environment.GetEnvironmentVariable("AZURE_BING_CONNECTION_ID");
BingGroundingToolDefinition bingTool = new(
new BingGroundingSearchToolParameters(
[new BingGroundingSearchConfiguration(bingConnectionId)]
)
);
PersistentAgent agent = await client.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "Search Agent",
instructions: "Use Bing to answer questions about current events.",
tools: [bingTool]
);
8. Azure AI Search
AzureAISearchToolResource searchResource = new(
connectionId: searchConnectionId,
indexName: "my_index",
topK: 5,
filter: "category eq 'documentation'",
queryType: AzureAISearchQueryType.Simple
);
PersistentAgent agent = await client.Administration.CreateAgentAsync(
model: modelDeploymentName,
name: "Search Agent",
instructions: "Search the documentation index to answer questions.",
tools: [new AzureAISearchToolDefinition()],
toolResources: new ToolResources { AzureAISearch = searchResource }
);
9. Cleanup
await client.Threads.DeleteThreadAsync(thread.Id);
await client.Administration.DeleteAgentAsync(agent.Id);
await client.VectorStores.DeleteVectorStoreAsync(vectorStore.Id);
await client.Files.DeleteFileAsync(file.Id);
Available Tools
| Tool | Class | Purpose |
|---|---|---|
| Code Interpreter | CodeInterpreterToolDefinition | Execute Python code, generate visualizations |
| File Search | FileSearchToolDefinition | Search uploaded files via vector stores |
| Function Calling | FunctionToolDefinition | Call custom functions |
| Bing Grounding | BingGroundingToolDefinition | Web search via Bing |
| Azure AI Search | AzureAISearchToolDefinition | Search Azure AI Search indexes |
| OpenAPI | OpenApiToolDefinition | Call external APIs via OpenAPI spec |
| Azure Functions | AzureFunctionToolDefinition | Invoke Azure Functions |
| MCP | MCPToolDefinition | Model Context Protocol tools |
| SharePoint | SharepointToolDefinition | Access SharePoint content |
| Microsoft Fabric | MicrosoftFabricToolDefinition | Access Fabric data |
Streaming Update Types
| Update Type | Description |
|---|---|
StreamingUpdateReason.RunCreated | Run started |
StreamingUpdateReason.RunInProgress | Run processing |
StreamingUpdateReason.RunCompleted | Run finished |
StreamingUpdateReason.RunFailed | Run errored |
MessageContentUpdate | Text content chunk |
RunStepUpdate | Step status change |
Key Types Reference
| Type | Purpose |
|---|---|
PersistentAgentsClient | Main entry point |
PersistentAgent | Agent with model, instructions, tools |
PersistentAgentThread | Conversation thread |
PersistentThreadMessage | Message in thread |
ThreadRun | Execution of agent against thread |
RunStatus | Queued, InProgress, RequiresAction, Completed, Failed |
ToolResources | Combined tool resources |
ToolOutput | Function call response |
Best Practices
- Reuse SDK clients according to the installed SDK lifetime guidance; do not assume every client implements IDisposable
- Poll with appropriate delays — 500ms recommended between status checks
- Clean up resources — Delete threads and agents when done
- Handle all run statuses — Check for
RequiresAction,Failed,Cancelled - Use streaming for real-time UX — Better user experience than polling
- Store IDs not objects — Reference agents/threads by ID
- Use async methods — All operations should be async
Error Handling
using Azure;
try
{
var agent = await client.Administration.CreateAgentAsync(...);
}
catch (RequestFailedException ex) when (ex.Status == 404)
{
Console.WriteLine("Resource not found");
}
catch (RequestFailedException ex)
{
Console.WriteLine($"Error: {ex.Status} - {ex.ErrorCode}: {ex.Message}");
}
Related SDKs
| SDK | Purpose | Install |
|---|---|---|
Azure.AI.Agents.Persistent | Low-level agents (this SDK) | dotnet add package Azure.AI.Agents.Persistent |
Azure.AI.Projects | High-level project client | dotnet add package Azure.AI.Projects |
Reference Links
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure AI Projects SDK for Java
High-level SDK for Azure AI Foundry project management with access to connections, datasets, indexes, and evaluations.
Version and data boundary
This guide names a historical beta SDK. Inspect the selected artifact’s exact API before using client-builder/model signatures; pin compatible identity/core dependencies and compile a minimal test. Use synthetic data in an authorized test project. Dataset upload, index mutation, evaluation provider charges and schedules are separate effects; inspect destination, retention and cost before executing. Never log connection credentials.
Installation
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-projects</artifactId>
<version>1.0.0-beta.1</version>
</dependency>
Environment Variables
PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
Authentication
import com.azure.ai.projects.AIProjectClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
AIProjectClientBuilder builder = new AIProjectClientBuilder()
.endpoint(System.getenv("PROJECT_ENDPOINT"))
.credential(new DefaultAzureCredentialBuilder().build());
Client Hierarchy
The SDK provides multiple sub-clients for different operations:
| Client | Purpose |
|---|---|
ConnectionsClient | Enumerate connected Azure resources |
DatasetsClient | Upload documents and manage datasets |
DeploymentsClient | Enumerate AI model deployments |
IndexesClient | Create and manage search indexes |
EvaluationsClient | Run AI model evaluations |
EvaluatorsClient | Manage evaluator configurations |
SchedulesClient | Manage scheduled operations |
// Build sub-clients from builder
ConnectionsClient connectionsClient = builder.buildConnectionsClient();
DatasetsClient datasetsClient = builder.buildDatasetsClient();
DeploymentsClient deploymentsClient = builder.buildDeploymentsClient();
IndexesClient indexesClient = builder.buildIndexesClient();
EvaluationsClient evaluationsClient = builder.buildEvaluationsClient();
Core Operations
List Connections
import com.azure.ai.projects.models.Connection;
import com.azure.core.http.rest.PagedIterable;
PagedIterable<Connection> connections = connectionsClient.listConnections();
for (Connection connection : connections) {
System.out.println("Name: " + connection.getName());
System.out.println("Type: " + connection.getType());
System.out.println("Credential Type: " + connection.getCredentials().getType());
}
List Indexes
indexesClient.listLatest().forEach(index -> {
System.out.println("Index name: " + index.getName());
System.out.println("Version: " + index.getVersion());
System.out.println("Description: " + index.getDescription());
});
Create or Update Index
import com.azure.ai.projects.models.AzureAISearchIndex;
import com.azure.ai.projects.models.Index;
String indexName = "my-index";
String indexVersion = "1.0";
String searchConnectionName = System.getenv("AI_SEARCH_CONNECTION_NAME");
String searchIndexName = System.getenv("AI_SEARCH_INDEX_NAME");
Index index = indexesClient.createOrUpdate(
indexName,
indexVersion,
new AzureAISearchIndex()
.setConnectionName(searchConnectionName)
.setIndexName(searchIndexName)
);
System.out.println("Created index: " + index.getName());
Evaluation integration
Do not assume an EvaluationsClient is an OpenAI EvalService or exposes getOpenAIClient(). Check the exact installed beta SDK reference and construct the documented evaluation client for that API. These are distinct SDK surfaces and require compatible dependencies, endpoints and authorization.
Best Practices
- Use DefaultAzureCredential for production authentication
- Reuse client builder to create multiple sub-clients efficiently
- Handle pagination when listing resources with
PagedIterable - Use environment variables for connection names and configuration
- Check connection types before accessing credentials
Error Handling
import com.azure.core.exception.HttpResponseException;
import com.azure.core.exception.ResourceNotFoundException;
try {
Index index = indexesClient.get(indexName, version);
} catch (ResourceNotFoundException e) {
System.err.println("Index not found: " + indexName);
} catch (HttpResponseException e) {
System.err.println("Error: " + e.getResponse().getStatusCode());
}
Reference Links
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure.AI.VoiceLive (.NET)
Real-time voice AI SDK for building bidirectional voice assistants with Azure AI.
Installation
dotnet add package Azure.AI.VoiceLive
dotnet add package Azure.Identity
dotnet add package NAudio # For audio capture/playback
Version scope: Examples are SDK fragments; pin a compatible package and check its API/model availability in the linked Microsoft documentation rather than treating these examples as a current version list.
Environment Variables
AZURE_VOICELIVE_ENDPOINT=https://<resource>.services.ai.azure.com/
AZURE_VOICELIVE_MODEL=gpt-4o-realtime-preview
AZURE_VOICELIVE_VOICE=en-US-AvaNeural
# Optional: API key if not using Entra ID
AZURE_VOICELIVE_API_KEY=<your-api-key>
Authentication
Microsoft Entra ID (Recommended)
using Azure.Identity;
using Azure.AI.VoiceLive;
Uri endpoint = new Uri("https://your-resource.cognitiveservices.azure.com");
DefaultAzureCredential credential = new DefaultAzureCredential();
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);
Required Role: Cognitive Services User (assign in Azure Portal → Access control)
API Key
Uri endpoint = new Uri("https://your-resource.cognitiveservices.azure.com");
AzureKeyCredential credential = new AzureKeyCredential("your-api-key");
VoiceLiveClient client = new VoiceLiveClient(endpoint, credential);
Client Hierarchy
VoiceLiveClient
└── VoiceLiveSession (WebSocket connection)
├── ConfigureSessionAsync()
├── GetUpdatesAsync() → SessionUpdate events
├── AddItemAsync() → UserMessageItem, FunctionCallOutputItem
├── SendAudioAsync()
└── StartResponseAsync()
Voice and tool boundaries
Obtain applicable microphone/recording/transmission consent, select an approved Azure resource/region and bound session duration/costs. Model-provided tool arguments are untrusted: validate schema, allowlist operations, and require authorization for external effects. Do not place secrets in instructions/logs or treat a function definition as an executed integration. Reconfigure the session after adding tools; exact audio formats/rates depend on the pinned model and SDK.
Core Workflow
1. Start Session and Configure
using Azure.Identity;
using Azure.AI.VoiceLive;
var endpoint = new Uri(Environment.GetEnvironmentVariable("AZURE_VOICELIVE_ENDPOINT"));
var client = new VoiceLiveClient(endpoint, new DefaultAzureCredential());
var model = "gpt-4o-mini-realtime-preview";
// Start session
using VoiceLiveSession session = await client.StartSessionAsync(model);
// Configure session
VoiceLiveSessionOptions sessionOptions = new()
{
Model = model,
Instructions = "You are a helpful AI assistant. Respond naturally.",
Voice = new AzureStandardVoice("en-US-AvaNeural"),
TurnDetection = new AzureSemanticVadTurnDetection()
{
Threshold = 0.5f,
PrefixPadding = TimeSpan.FromMilliseconds(300),
SilenceDuration = TimeSpan.FromMilliseconds(500)
},
InputAudioFormat = InputAudioFormat.Pcm16,
OutputAudioFormat = OutputAudioFormat.Pcm16
};
// Set modalities (both text and audio for voice assistants)
sessionOptions.Modalities.Clear();
sessionOptions.Modalities.Add(InteractionModality.Text);
sessionOptions.Modalities.Add(InteractionModality.Audio);
await session.ConfigureSessionAsync(sessionOptions);
2. Process Events
await foreach (SessionUpdate serverEvent in session.GetUpdatesAsync())
{
switch (serverEvent)
{
case SessionUpdateResponseAudioDelta audioDelta:
byte[] audioData = audioDelta.Delta.ToArray();
// Play audio via NAudio or other audio library
break;
case SessionUpdateResponseTextDelta textDelta:
Console.Write(textDelta.Delta);
break;
case SessionUpdateResponseFunctionCallArgumentsDone functionCall:
// Handle function call (see Function Calling section)
break;
case SessionUpdateError error:
Console.WriteLine($"Error: {error.Error.Message}");
break;
case SessionUpdateResponseDone:
Console.WriteLine("\n--- Response complete ---");
break;
}
}
3. Send User Message
await session.AddItemAsync(new UserMessageItem("Hello, can you help me?"));
await session.StartResponseAsync();
4. Function Calling
// Define function
var weatherFunction = new VoiceLiveFunctionDefinition("get_current_weather")
{
Description = "Get the current weather for a given location",
Parameters = BinaryData.FromString("""
{
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "The city and state or country"
}
},
"required": ["location"]
}
""")
};
// Add to session options
sessionOptions.Tools.Add(weatherFunction);
// Handle function call in event loop
if (serverEvent is SessionUpdateResponseFunctionCallArgumentsDone functionCall)
{
if (functionCall.Name == "get_current_weather")
{
var parameters = JsonSerializer.Deserialize<Dictionary<string, string>>(functionCall.Arguments);
if (parameters is null || !parameters.TryGetValue("location", out string? location)
|| string.IsNullOrWhiteSpace(location))
throw new ArgumentException("location is required");
// Call external service
string weatherInfo = $"Demo only: no live weather lookup was performed for {location}.";
// Send response
await session.AddItemAsync(new FunctionCallOutputItem(functionCall.CallId, weatherInfo));
await session.StartResponseAsync();
}
}
Voice Options
| Voice Type | Class | Example |
|---|---|---|
| Azure Standard | AzureStandardVoice | "en-US-AvaNeural" |
| Azure HD | AzureStandardVoice | "en-US-Ava:DragonHDLatestNeural" |
| Azure Custom | AzureCustomVoice | Custom voice with endpoint ID |
Supported Models
| Model | Description |
|---|---|
gpt-4o-realtime-preview | GPT-4o with real-time audio |
gpt-4o-mini-realtime-preview | Lightweight, fast interactions |
phi4-mm-realtime | Cost-effective multimodal |
Key Types Reference
| Type | Purpose |
|---|---|
VoiceLiveClient | Main client for creating sessions |
VoiceLiveSession | Active WebSocket session |
VoiceLiveSessionOptions | Session configuration |
AzureStandardVoice | Standard Azure voice provider |
AzureSemanticVadTurnDetection | Voice activity detection |
VoiceLiveFunctionDefinition | Function tool definition |
UserMessageItem | User text message |
FunctionCallOutputItem | Function call response |
SessionUpdateResponseAudioDelta | Audio chunk event |
SessionUpdateResponseTextDelta | Text chunk event |
Best Practices
- Always set both modalities — Include
TextandAudiofor voice assistants - Use
AzureSemanticVadTurnDetection— Provides natural conversation flow - Configure appropriate silence duration — 500ms typical to avoid premature cutoffs
- Use
usingstatement — Ensures proper session disposal - Handle all event types — Check for errors, audio, text, and function calls
- Use DefaultAzureCredential — Never hardcode API keys
Error Handling
if (serverEvent is SessionUpdateError error)
{
if (error.Error.Message.Contains("Cancellation failed: no active response"))
{
// Benign error, can ignore
}
else
{
Console.WriteLine($"Error: {error.Error.Message}");
}
}
Audio Configuration
- Input Format:
InputAudioFormat.Pcm16(16-bit PCM) - Output Format:
OutputAudioFormat.Pcm16 - Sample Rate: 24kHz recommended
- Channels: Mono
Related SDKs
| SDK | Purpose | Install |
|---|---|---|
Azure.AI.VoiceLive | Real-time voice (this SDK) | dotnet add package Azure.AI.VoiceLive |
Microsoft.CognitiveServices.Speech | Speech-to-text, text-to-speech | dotnet add package Microsoft.CognitiveServices.Speech |
NAudio | Audio capture/playback | dotnet add package NAudio |
Reference Links
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Cosmos DB SDK for Rust
Client library for Azure Cosmos DB NoSQL API — globally distributed, multi-model database.
The examples below require a reviewed compatible crate set and replacement of every resource placeholder. Do not use production data for demonstration writes.
Installation
cargo add azure_data_cosmos@=0.37.1 azure_identity@=1.0.0 azure_core@=1.1.0
Environment Variables
export COSMOS_ENDPOINT="https://<account>.documents.azure.com:443/"
export COSMOS_DATABASE="mydb"
export COSMOS_CONTAINER="mycontainer"
Authentication
use azure_identity::DeveloperToolsCredential;
use azure_data_cosmos::{AccountEndpoint, AccountReference, CosmosClient, RoutingStrategy};
let credential = DeveloperToolsCredential::new(None)?;
let endpoint: AccountEndpoint = "https://<account>.documents.azure.com/".parse()?;
let account = AccountReference::with_credential(endpoint, credential.clone());
let client = CosmosClient::builder()
.build(account, RoutingStrategy::ProximityTo("East US".into()))
.await?;
Client Hierarchy
| Client | Purpose | Get From |
|---|---|---|
CosmosClient | Account-level operations | Direct instantiation |
DatabaseClient | Database operations | client.database_client() |
ContainerClient | Container/item operations | database.container_client() |
Core Workflow
Get Database and Container Clients
let database = client.database_client("myDatabase");
let container = database.container_client("myContainer", None).await?;
Create Item
use serde::{Serialize, Deserialize};
#[derive(Serialize, Deserialize)]
struct Item {
pub id: String,
pub partition_key: String,
pub value: String,
}
let item = Item {
id: "1".into(),
partition_key: "partition1".into(),
value: "hello".into(),
};
container.create_item("partition1", "1", item, None).await?;
Read Item
let response = container.read_item("partition1", "1", None).await?;
let item: Item = response.into_model()?;
Replace Item
let mut item: Item = container.read_item("partition1", "1", None).await?.into_model()?;
item.value = "updated".into();
container.replace_item("partition1", "1", item, None).await?;
Patch Item
// Explicit preview opt-in: cargo add azure_data_cosmos@=0.37.1 --features preview_patch
use azure_data_cosmos::models::{PatchInstructions, PatchOperation};
let patch = PatchInstructions::from(vec![
PatchOperation::set("/value", serde_json::json!("newValue")),
]);
let patched: Item = container.patch_item("partition1", "1", patch, None)
.await?.into_model()?;
Delete Item
container.delete_item("partition1", "1", None).await?;
The reviewed current API uses an async builder/container initialization and a separate explicit item ID. Preview PATCH is not a production-ready guarantee; review its selected strategy, conflict/retry behavior and request-unit cost. Official crate reference.
Key Auth (Optional)
Enable key-based authentication with feature flag:
cargo add azure_data_cosmos@=0.37.1 --features key_auth
Best Practices
- Always specify partition key — required for point reads and writes
- Use
into_model()?— to deserialize responses into your types - Derive
SerializeandDeserialize— for all document types - Use Entra ID auth — prefer
DeveloperToolsCredentialover key auth - Reuse client instances — clients are thread-safe and reusable
The reviewed example set uses azure_data_cosmos 0.37.1 and compatible Azure core/credential crates. Record and commit Cargo.lock; source/API review is not a compiler or live-service test.
Reference Links
| Resource | Link |
|---|---|
| API Reference | https://docs.rs/azure_data_cosmos |
| Source Code | https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/cosmos/azure_data_cosmos |
| crates.io | https://crates.io/crates/azure_data_cosmos |
When to Use
Use when a Rust application needs Cosmos DB NoSQL item CRUD, partition-key point reads, container access or explicitly opted-in preview patching.
Limitations
- Examples are fragments inside async application code, with compatible pinned Azure crates and the required Tokio/Serde/Futures dependencies; verify the selected version’s API before use. They were reviewed against official source/reference, not compiled or run against a cloud account here.
- Use an authorized tenant, resource and identity with least privilege. Writes, overwrites, deletes, backup retrieval and account changes require the corresponding scope; cleanup may remove only explicitly identified disposable resources. Bound requests, retries and downloaded bytes, and do not log payloads, credentials or secret values.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
@azure/cosmos (TypeScript/JavaScript)
Data plane SDK for Azure Cosmos DB NoSQL API operations — CRUD on documents, queries, bulk operations.
⚠️ Data vs Management Plane
- This SDK (@azure/cosmos): CRUD operations on documents, queries, stored procedures
- Management SDK (@azure/arm-cosmosdb): Create accounts, databases, containers via ARM
Installation
npm install @azure/cosmos @azure/identity
Current Version: 4.9.0
Node.js: >= 20.0.0
Environment Variables
COSMOS_ENDPOINT=https://<account>.documents.azure.com:443/
COSMOS_DATABASE=<database-name>
COSMOS_CONTAINER=<container-name>
# For key-based auth only (prefer AAD)
COSMOS_KEY=<account-key>
Authentication
AAD with DefaultAzureCredential (Recommended)
import { CosmosClient } from "@azure/cosmos";
import { DefaultAzureCredential } from "@azure/identity";
const client = new CosmosClient({
endpoint: process.env.COSMOS_ENDPOINT!,
aadCredentials: new DefaultAzureCredential(),
});
Key-Based Authentication
import { CosmosClient } from "@azure/cosmos";
// Option 1: Endpoint + Key
const client = new CosmosClient({
endpoint: process.env.COSMOS_ENDPOINT!,
key: process.env.COSMOS_KEY!,
});
// Option 2: Connection String
const client = new CosmosClient(process.env.COSMOS_CONNECTION_STRING!);
Resource Hierarchy
CosmosClient
└── Database
└── Container
├── Items (documents)
├── Scripts (stored procedures, triggers, UDFs)
└── Conflicts
Core Operations
Confirm account/database/container, tenant-bound authorization and write/delete scope first. Partition keys are routing, not authorization. Bound query pages, RU cost, retries and runtime; fetchAll may be unbounded. Bulk operations are not an all-or-nothing transaction: inspect each response/error and retry only eligible failed items with idempotency/concurrency checks. Pin SDK versions and verify examples against Microsoft SDK docs.
Database & Container Setup
const { database } = await client.databases.createIfNotExists({
id: "my-database",
});
const { container } = await database.containers.createIfNotExists({
id: "my-container",
partitionKey: { paths: ["/partitionKey"] },
});
Create Document
interface Product {
id: string;
partitionKey: string;
name: string;
price: number;
}
const item: Product = {
id: "product-1",
partitionKey: "electronics",
name: "Laptop",
price: 999.99,
};
const { resource } = await container.items.create<Product>(item);
Read Document
const { resource } = await container
.item("product-1", "electronics") // id, partitionKey
.read<Product>();
if (resource) {
console.log(resource.name);
}
Update Document (Replace)
const { resource: existing } = await container
.item("product-1", "electronics")
.read<Product>();
if (existing) {
existing.price = 899.99;
const { resource: updated } = await container
.item("product-1", "electronics")
.replace<Product>(existing);
}
Upsert Document
const item: Product = {
id: "product-1",
partitionKey: "electronics",
name: "Laptop Pro",
price: 1299.99,
};
const { resource } = await container.items.upsert<Product>(item);
Delete Document
await container.item("product-1", "electronics").delete();
Patch Document (Partial Update)
import { PatchOperation } from "@azure/cosmos";
const operations: PatchOperation[] = [
{ op: "replace", path: "/price", value: 799.99 },
{ op: "add", path: "/discount", value: true },
{ op: "remove", path: "/oldField" },
];
const { resource } = await container
.item("product-1", "electronics")
.patch<Product>(operations);
Queries
Simple Query
const { resources } = await container.items
.query<Product>("SELECT * FROM c WHERE c.price < 1000")
.fetchAll();
Parameterized Query (Recommended)
import { SqlQuerySpec } from "@azure/cosmos";
const querySpec: SqlQuerySpec = {
query: "SELECT * FROM c WHERE c.partitionKey = @category AND c.price < @maxPrice",
parameters: [
{ name: "@category", value: "electronics" },
{ name: "@maxPrice", value: 1000 },
],
};
const { resources } = await container.items
.query<Product>(querySpec)
.fetchAll();
Query with Pagination
const queryIterator = container.items.query<Product>(querySpec, {
maxItemCount: 10, // Items per page
});
while (queryIterator.hasMoreResults()) {
const { resources, continuationToken } = await queryIterator.fetchNext();
console.log(`Page with ${resources?.length} items`);
// Use continuationToken for next page if needed
}
Cross-Partition Query
const { resources } = await container.items
.query<Product>(
"SELECT * FROM c WHERE c.price > 500",
{ enableCrossPartitionQuery: true }
)
.fetchAll();
Bulk Operations
Execute Bulk Operations
import { BulkOperationType, OperationInput } from "@azure/cosmos";
const operations: OperationInput[] = [
{
operationType: BulkOperationType.Create,
resourceBody: { id: "1", partitionKey: "cat-a", name: "Item 1" },
},
{
operationType: BulkOperationType.Upsert,
resourceBody: { id: "2", partitionKey: "cat-a", name: "Item 2" },
},
{
operationType: BulkOperationType.Read,
id: "3",
partitionKey: "cat-b",
},
{
operationType: BulkOperationType.Replace,
id: "4",
partitionKey: "cat-b",
resourceBody: { id: "4", partitionKey: "cat-b", name: "Updated" },
},
{
operationType: BulkOperationType.Delete,
id: "5",
partitionKey: "cat-c",
},
{
operationType: BulkOperationType.Patch,
id: "6",
partitionKey: "cat-c",
resourceBody: {
operations: [{ op: "replace", path: "/name", value: "Patched" }],
},
},
];
const response = await container.items.executeBulkOperations(operations);
response.forEach((result, index) => {
const statusCode = result.response?.statusCode;
if (!result.error && statusCode !== undefined && statusCode >= 200 && statusCode < 300) {
console.log(`Operation ${index} succeeded`);
} else {
console.error(`Operation ${index} failed: ${statusCode ?? result.error?.code ?? "unknown"}`);
}
});
Partition Keys
Simple Partition Key
const { container } = await database.containers.createIfNotExists({
id: "products",
partitionKey: { paths: ["/category"] },
});
Hierarchical Partition Key (MultiHash)
import { PartitionKeyDefinitionVersion, PartitionKeyKind } from "@azure/cosmos";
const { container } = await database.containers.createIfNotExists({
id: "orders",
partitionKey: {
paths: ["/tenantId", "/userId", "/sessionId"],
version: PartitionKeyDefinitionVersion.V2,
kind: PartitionKeyKind.MultiHash,
},
});
// Operations require array of partition key values
const { resource } = await container.items.create({
id: "order-1",
tenantId: "tenant-a",
userId: "user-123",
sessionId: "session-xyz",
total: 99.99,
});
// Read with hierarchical partition key
const { resource: order } = await container
.item("order-1", ["tenant-a", "user-123", "session-xyz"])
.read();
Error Handling
import { ErrorResponse } from "@azure/cosmos";
try {
const { resource } = await container.item("missing", "pk").read();
} catch (error) {
if (error instanceof ErrorResponse) {
switch (error.code) {
case 404:
console.log("Document not found");
break;
case 409:
console.log("Conflict - document already exists");
break;
case 412:
console.log("Precondition failed (ETag mismatch)");
break;
case 429:
console.log("Rate limited - retry after:", error.retryAfterInMs);
break;
default:
console.error(`Cosmos error ${error.code}: ${error.message}`);
}
}
throw error;
}
Optimistic Concurrency (ETags)
// Read with ETag
const { resource, etag } = await container
.item("product-1", "electronics")
.read<Product>();
if (resource && etag) {
resource.price = 899.99;
try {
// Replace only if ETag matches
await container.item("product-1", "electronics").replace(resource, {
accessCondition: { type: "IfMatch", condition: etag },
});
} catch (error) {
if (error instanceof ErrorResponse && error.code === 412) {
console.log("Document was modified by another process");
}
}
}
TypeScript Types Reference
import {
// Client & Resources
CosmosClient,
Database,
Container,
Item,
Items,
// Operations
OperationInput,
BulkOperationType,
PatchOperation,
// Queries
SqlQuerySpec,
SqlParameter,
FeedOptions,
// Partition Keys
PartitionKeyDefinition,
PartitionKeyDefinitionVersion,
PartitionKeyKind,
// Responses
ItemResponse,
FeedResponse,
ResourceResponse,
// Errors
ErrorResponse,
} from "@azure/cosmos";
Best Practices
- Use AAD authentication — Prefer
DefaultAzureCredentialover keys - Always use parameterized queries — Prevents injection, improves plan caching
- Specify partition key — Avoid cross-partition queries when possible
- Use bulk operations — For multiple writes, use
executeBulkOperations - Handle 429 errors — Implement retry logic with exponential backoff
- Use ETags for concurrency — Prevent lost updates in concurrent scenarios
- Close client on shutdown — Call
client.dispose()in cleanup
Common Patterns
Service Layer Pattern
export class ProductService {
private container: Container;
constructor(client: CosmosClient) {
this.container = client
.database(process.env.COSMOS_DATABASE!)
.container(process.env.COSMOS_CONTAINER!);
}
async getById(id: string, category: string): Promise<Product | null> {
try {
const { resource } = await this.container
.item(id, category)
.read<Product>();
return resource ?? null;
} catch (error) {
if (error instanceof ErrorResponse && error.code === 404) {
return null;
}
throw error;
}
}
async create(product: Omit<Product, "id">): Promise<Product> {
const item = { ...product, id: crypto.randomUUID() };
const { resource } = await this.container.items.create<Product>(item);
return resource!;
}
async findByCategory(category: string): Promise<Product[]> {
const querySpec: SqlQuerySpec = {
query: "SELECT * FROM c WHERE c.partitionKey = @category",
parameters: [{ name: "@category", value: category }],
};
const { resources } = await this.container.items
.query<Product>(querySpec)
.fetchAll();
return resources;
}
}
Related SDKs
| SDK | Purpose | Install |
|---|---|---|
@azure/cosmos | Data plane (this SDK) | npm install @azure/cosmos |
@azure/arm-cosmosdb | Management plane (ARM) | npm install @azure/arm-cosmosdb |
@azure/identity | Authentication | npm install @azure/identity |
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Event Grid SDK for Java
Build event-driven applications using the Azure Event Grid SDK for Java.
Integration boundaries
Use the SDK/reference matching the pinned package; namespace pull examples require the separate namespace client dependency. Authenticate/validate webhook sources, bound payloads and deduplicate event IDs. Acknowledge received events only after durable successful processing; failures must be released/retried or dead-lettered under policy. Publishing can trigger downstream actions/costs, so use an authorized topic and synthetic data. Service size limits vary by feature/tier; consult current quotas rather than assuming the summary below is a complete limit table.
Installation
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-messaging-eventgrid</artifactId>
<version>4.27.0</version>
</dependency>
Client Creation
EventGridPublisherClient
import com.azure.messaging.eventgrid.EventGridPublisherClient;
import com.azure.messaging.eventgrid.EventGridPublisherClientBuilder;
import com.azure.core.credential.AzureKeyCredential;
// With API Key
EventGridPublisherClient<EventGridEvent> client = new EventGridPublisherClientBuilder()
.endpoint("<topic-endpoint>")
.credential(new AzureKeyCredential("<access-key>"))
.buildEventGridEventPublisherClient();
// For CloudEvents
EventGridPublisherClient<CloudEvent> cloudClient = new EventGridPublisherClientBuilder()
.endpoint("<topic-endpoint>")
.credential(new AzureKeyCredential("<access-key>"))
.buildCloudEventPublisherClient();
With DefaultAzureCredential
import com.azure.identity.DefaultAzureCredentialBuilder;
EventGridPublisherClient<EventGridEvent> client = new EventGridPublisherClientBuilder()
.endpoint("<topic-endpoint>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildEventGridEventPublisherClient();
Async Client
import com.azure.messaging.eventgrid.EventGridPublisherAsyncClient;
EventGridPublisherAsyncClient<EventGridEvent> asyncClient = new EventGridPublisherClientBuilder()
.endpoint("<topic-endpoint>")
.credential(new AzureKeyCredential("<access-key>"))
.buildEventGridEventPublisherAsyncClient();
Event Types
| Type | Description |
|---|---|
EventGridEvent | Azure Event Grid native schema |
CloudEvent | CNCF CloudEvents 1.0 specification |
BinaryData | Custom schema events |
Core Patterns
Publish EventGridEvent
import com.azure.messaging.eventgrid.EventGridEvent;
import com.azure.core.util.BinaryData;
EventGridEvent event = new EventGridEvent(
"resource/path", // subject
"MyApp.Events.OrderCreated", // eventType
BinaryData.fromObject(new OrderData("order-123", 99.99)), // data
"1.0" // dataVersion
);
client.sendEvent(event);
Publish Multiple Events
List<EventGridEvent> events = Arrays.asList(
new EventGridEvent("orders/1", "Order.Created",
BinaryData.fromObject(order1), "1.0"),
new EventGridEvent("orders/2", "Order.Created",
BinaryData.fromObject(order2), "1.0")
);
client.sendEvents(events);
Publish CloudEvent
import com.azure.core.models.CloudEvent;
import com.azure.core.models.CloudEventDataFormat;
CloudEvent cloudEvent = new CloudEvent(
"/myapp/orders", // source
"order.created", // type
BinaryData.fromObject(orderData), // data
CloudEventDataFormat.JSON // dataFormat
);
cloudEvent.setSubject("orders/12345");
cloudEvent.setId(UUID.randomUUID().toString());
cloudClient.sendEvent(cloudEvent);
Publish CloudEvents Batch
List<CloudEvent> cloudEvents = Arrays.asList(
new CloudEvent("/app", "event.type1", BinaryData.fromString("{\"value\":\"data1\"}"), CloudEventDataFormat.JSON),
new CloudEvent("/app", "event.type2", BinaryData.fromString("{\"value\":\"data2\"}"), CloudEventDataFormat.JSON)
);
cloudClient.sendEvents(cloudEvents);
Async Publishing
asyncClient.sendEvent(event)
.subscribe(
unused -> { },
error -> System.err.println("Error: " + error.getMessage()),
() -> System.out.println("Event sent successfully")
);
// With multiple events
asyncClient.sendEvents(events)
.doOnSuccess(unused -> System.out.println("All events sent"))
.doOnError(error -> System.err.println("Failed: " + error))
.block(); // Block if needed
Custom Event Data Class
public class OrderData {
private String orderId;
private double amount;
private String customerId;
public OrderData(String orderId, double amount) {
this.orderId = orderId;
this.amount = amount;
}
// Getters and setters
}
// Usage
OrderData order = new OrderData("ORD-123", 150.00);
EventGridEvent event = new EventGridEvent(
"orders/" + order.getOrderId(),
"MyApp.Order.Created",
BinaryData.fromObject(order),
"1.0"
);
Receiving Events
Parse EventGridEvent
import com.azure.messaging.eventgrid.EventGridEvent;
// From JSON string (e.g., webhook payload)
String jsonPayload = "[{\"id\": \"...\", ...}]";
List<EventGridEvent> events = EventGridEvent.fromString(jsonPayload);
for (EventGridEvent event : events) {
System.out.println("Event Type: " + event.getEventType());
System.out.println("Subject: " + event.getSubject());
System.out.println("Event Time: " + event.getEventTime());
// Get data
BinaryData data = event.getData();
OrderData orderData = data.toObject(OrderData.class);
}
Parse CloudEvent
import com.azure.core.models.CloudEvent;
String cloudEventJson = "[{\"specversion\": \"1.0\", ...}]";
List<CloudEvent> cloudEvents = CloudEvent.fromString(cloudEventJson);
for (CloudEvent event : cloudEvents) {
System.out.println("Type: " + event.getType());
System.out.println("Source: " + event.getSource());
System.out.println("ID: " + event.getId());
MyEventData data = event.getData().toObject(MyEventData.class);
}
Handle System Events
import com.azure.messaging.eventgrid.systemevents.*;
for (EventGridEvent event : events) {
if (event.getEventType().equals("Microsoft.Storage.BlobCreated")) {
StorageBlobCreatedEventData blobData =
event.getData().toObject(StorageBlobCreatedEventData.class);
System.out.println("Blob URL: " + blobData.getUrl());
}
}
Event Grid Namespaces (MQTT/Pull)
Receive from Namespace Topic
import com.azure.messaging.eventgrid.namespaces.EventGridReceiverClient;
import com.azure.messaging.eventgrid.namespaces.EventGridReceiverClientBuilder;
import com.azure.messaging.eventgrid.namespaces.models.*;
EventGridReceiverClient receiverClient = new EventGridReceiverClientBuilder()
.endpoint("<namespace-endpoint>")
.credential(new AzureKeyCredential("<key>"))
.topicName("my-topic")
.subscriptionName("my-subscription")
.buildClient();
// Receive events
ReceiveResult result = receiverClient.receive(10, Duration.ofSeconds(30));
for (ReceiveDetails detail : result.getValue()) {
CloudEvent event = detail.getEvent();
System.out.println("Event: " + event.getType());
// Acknowledge the event
receiverClient.acknowledge(Arrays.asList(detail.getBrokerProperties().getLockToken()));
}
Reject or Release Events
// Reject (don't retry)
receiverClient.reject(Arrays.asList(lockToken));
// Release (retry later)
receiverClient.release(Arrays.asList(lockToken));
// Release with delay
receiverClient.release(Arrays.asList(lockToken),
new ReleaseOptions().setDelay(ReleaseDelay.BY_60_SECONDS));
Error Handling
import com.azure.core.exception.HttpResponseException;
try {
client.sendEvent(event);
} catch (HttpResponseException e) {
System.out.println("Status: " + e.getResponse().getStatusCode());
System.out.println("Error: " + e.getMessage());
}
Environment Variables
EVENT_GRID_TOPIC_ENDPOINT=https://<topic-name>.<region>.eventgrid.azure.net/api/events
EVENT_GRID_ACCESS_KEY=<your-access-key>
Best Practices
- Batch Events: Send multiple events in one call when possible
- Idempotency: Include unique event IDs for deduplication
- Schema Validation: Use strongly-typed event data classes
- Retry Logic: Built-in, but consider dead-letter for failures
- Event Size: Keep events under 1MB (64KB for basic tier)
Trigger Phrases
- "Event Grid Java"
- "publish events Azure"
- "CloudEvent SDK"
- "event-driven messaging"
- "pub/sub Azure"
- "webhook events"
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Event Hubs SDK for Rust
Client library for Azure Event Hubs — big data streaming platform and event ingestion service.
The examples below require a reviewed compatible crate set and replacement of every resource placeholder. Do not use production data for demonstration writes.
Installation
cargo add azure_messaging_eventhubs@=0.16.0 azure_identity@=1.1.0-beta.1 azure_core@=1.2.0-beta.1
Environment Variables
export EVENTHUBS_HOST="<namespace>.servicebus.windows.net"
export EVENTHUB_NAME="<eventhub-name>"
Key Concepts
- Namespace — container for Event Hubs
- Event Hub — stream of events partitioned for parallel processing
- Partition — ordered sequence of events
- Producer — sends events to Event Hub
- Consumer — receives events from partitions
Producer Client
Create Producer
use azure_identity::DeveloperToolsCredential;
use azure_messaging_eventhubs::ProducerClient;
let credential = DeveloperToolsCredential::new(None)?;
let producer = ProducerClient::builder()
.open("<namespace>.servicebus.windows.net", "eventhub-name", credential.clone())
.await?;
Send Single Event
producer.send_event(vec![1, 2, 3, 4], None).await?;
Send Batch
let batch = producer.create_batch(None).await?;
if !batch.try_add_event_data(b"event 1".to_vec(), None)? {
return Err("Event does not fit in the batch".into());
}
if !batch.try_add_event_data(b"event 2".to_vec(), None)? {
return Err("Send the existing batch and retry the remaining event in a new batch".into());
}
producer.send_batch(batch, None).await?;
Consumer Client
Create Consumer
use azure_messaging_eventhubs::ConsumerClient;
let credential = DeveloperToolsCredential::new(None)?;
let consumer = ConsumerClient::builder()
.open("<namespace>.servicebus.windows.net", "eventhub-name", credential.clone())
.await?;
Receive Events
// Open receiver for specific partition
use futures::StreamExt;
let receiver = consumer.open_receiver_on_partition("0".to_string(), None).await?;
let mut events = receiver.stream_events();
// Bound the receive loop and handle the no-event timeout without logging payloads.
for _ in 0..100 {
match tokio::time::timeout(std::time::Duration::from_secs(10), events.next()).await {
Ok(Some(Ok(event))) => { /* process the authorized event and checkpoint safely */ }
Ok(Some(Err(error))) => return Err(error.into()),
Ok(None) | Err(_) => break,
}
}
Get Event Hub Properties
let properties = consumer.get_eventhub_properties(None).await?;
println!("Partitions: {:?}", properties.partition_ids);
Get Partition Properties
let partition_props = consumer.get_partition_properties("0", None).await?;
println!("Last sequence number: {}", partition_props.last_enqueued_sequence_number);
Best Practices
- Reuse clients — create once, send many events
- Use batches — more efficient than individual sends
- Check batch capacity —
try_add_event_datareturns false when full - Process partitions in parallel — each partition can be consumed independently
- Use consumer groups — isolate different consuming applications
- Handle checkpointing — use
azure_messaging_eventhubs_checkpointstore_blobfor distributed consumers
Checkpoint Store (Optional)
For distributed consumers with checkpointing:
cargo add azure_messaging_eventhubs_checkpointstore_blob
Event Hubs 0.16 uses the Azure core beta line, so pair it with the published matching identity beta; do not mix credential traits from the stable core line.
The reviewed example set uses azure_messaging_eventhubs 0.16.0 and compatible Azure core/credential crates. Record and commit Cargo.lock; source/API review is not a compiler or live-service test.
Reference Links
When to Use
Use when a Rust application publishes individual/batched events or consumes a specific Event Hubs partition with an explicit consumer group and checkpoint policy.
Limitations
- Examples are fragments inside async application code, with compatible pinned Azure crates and the required Tokio/Serde/Futures dependencies; verify the selected version’s API before use. They were reviewed against official source/reference, not compiled or run against a cloud account here.
- Use an authorized tenant, resource and identity with least privilege. Writes, overwrites, deletes, backup retrieval and account changes require the corresponding scope; cleanup may remove only explicitly identified disposable resources. Bound requests, retries and downloaded bytes, and do not log payloads, credentials or secret values.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Identity SDK for Python
Authentication library for Azure SDK clients using Microsoft Entra ID (formerly Azure AD).
Installation
pip install azure-identity
Environment Variables
# Service Principal (for production/CI)
AZURE_TENANT_ID=<your-tenant-id>
AZURE_CLIENT_ID=<your-client-id>
AZURE_CLIENT_SECRET=<your-client-secret>
# User-assigned Managed Identity (optional)
AZURE_CLIENT_ID=<managed-identity-client-id>
DefaultAzureCredential
Useful for development and flexible environments. Production should select an explicit intended credential (such as workload/managed identity) rather than unexpectedly falling back to another account. The chain below is illustrative and version/configuration-dependent:
from azure.identity import DefaultAzureCredential
from azure.storage.blob import BlobServiceClient
# Works in local dev AND production without code changes
credential = DefaultAzureCredential()
client = BlobServiceClient(
account_url="https://<account>.blob.core.windows.net",
credential=credential
)
Credential Chain Order
| Order | Credential | Environment |
|---|---|---|
| 1 | EnvironmentCredential | CI/CD, containers |
| 2 | WorkloadIdentityCredential | Kubernetes |
| 3 | ManagedIdentityCredential | Azure VMs, App Service, Functions |
| 4 | SharedTokenCacheCredential | Windows only |
| 5 | VisualStudioCodeCredential | VS Code with Azure extension |
| 6 | AzureCliCredential | az login |
| 7 | AzurePowerShellCredential | Connect-AzAccount |
| 8 | AzureDeveloperCliCredential | azd auth login |
Customizing DefaultAzureCredential
# Exclude credentials you don't need
credential = DefaultAzureCredential(
exclude_environment_credential=True,
exclude_shared_token_cache_credential=True,
managed_identity_client_id="<user-assigned-mi-client-id>" # For user-assigned MI
)
# Enable interactive browser (disabled by default)
credential = DefaultAzureCredential(
exclude_interactive_browser_credential=False
)
Before token acquisition, verify tenant, client/principal, cloud and required audience/scope without printing tokens. Avoid secrets in dotenv examples committed to a repo or pasted into shell history; prefer managed/workload identity where supported. Close credentials/clients in failure paths. Review the current credential-chain guidance for the selected package, including optional broker/developer credentials.
Specific Credential Types
ManagedIdentityCredential
For Azure-hosted resources (VMs, App Service, Functions, AKS):
from azure.identity import ManagedIdentityCredential
# System-assigned managed identity
credential = ManagedIdentityCredential()
# User-assigned managed identity
credential = ManagedIdentityCredential(
client_id="<user-assigned-mi-client-id>"
)
ClientSecretCredential
For service principal with secret:
import os
from azure.identity import ClientSecretCredential
credential = ClientSecretCredential(
tenant_id=os.environ["AZURE_TENANT_ID"],
client_id=os.environ["AZURE_CLIENT_ID"],
client_secret=os.environ["AZURE_CLIENT_SECRET"]
)
AzureCliCredential
Uses the account from az login:
from azure.identity import AzureCliCredential
credential = AzureCliCredential()
ChainedTokenCredential
Custom credential chain:
from azure.identity import (
ChainedTokenCredential,
ManagedIdentityCredential,
AzureCliCredential
)
# Try managed identity first, fall back to CLI
credential = ChainedTokenCredential(
ManagedIdentityCredential(client_id="<user-assigned-mi-client-id>"),
AzureCliCredential()
)
Credential Types Table
| Credential | Use Case | Auth Method |
|---|---|---|
DefaultAzureCredential | Most scenarios | Auto-detect |
ManagedIdentityCredential | Azure-hosted apps | Managed Identity |
ClientSecretCredential | Service principal | Client secret |
ClientCertificateCredential | Service principal | Certificate |
AzureCliCredential | Local development | Azure CLI |
AzureDeveloperCliCredential | Local development | Azure Developer CLI |
InteractiveBrowserCredential | User sign-in | Browser OAuth |
DeviceCodeCredential | Headless/SSH | Device code flow |
Getting Tokens Directly
from azure.identity import DefaultAzureCredential
credential = DefaultAzureCredential()
# Get token for a specific scope
token = credential.get_token("https://management.azure.com/.default")
print(f"Token expires: {token.expires_on}")
# For Azure Database for PostgreSQL
token = credential.get_token("https://ossrdbms-aad.database.windows.net/.default")
Async Client
from azure.identity.aio import DefaultAzureCredential
from azure.storage.blob.aio import BlobServiceClient
async def main():
credential = DefaultAzureCredential()
async with BlobServiceClient(
account_url="https://<account>.blob.core.windows.net",
credential=credential
) as client:
# ... async operations
pass
await credential.close()
Best Practices
- Use DefaultAzureCredential for code that runs locally and in Azure
- Never hardcode credentials — use environment variables or managed identity
- Prefer managed identity in production Azure deployments
- Use ChainedTokenCredential when you need a custom credential order
- Close async credentials explicitly or use context managers
- Set AZURE_CLIENT_ID for user-assigned managed identities
- Exclude unused credentials to speed up authentication
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Key Vault Secrets SDK for Rust
Client library for Azure Key Vault Secrets — secure storage for passwords, API keys, and other secrets.
The examples below require a reviewed compatible crate set and replacement of every resource placeholder. Do not use production data for demonstration writes.
Installation
cargo add azure_security_keyvault_secrets@=1.0.1 azure_identity@=1.0.0 azure_core@=1.1.0
Environment Variables
export AZURE_KEYVAULT_URL="https://<vault-name>.vault.azure.net/"
Authentication
use azure_identity::DeveloperToolsCredential;
use azure_security_keyvault_secrets::SecretClient;
let credential = DeveloperToolsCredential::new(None)?;
let client = SecretClient::new(
"https://<vault-name>.vault.azure.net/",
credential.clone(),
None,
)?;
Core Operations
Get Secret
let secret = client
.get_secret("secret-name", None)
.await?
.into_model()?;
let secret_value = secret.value.ok_or("Secret has no value")?;
// Pass directly to the authorized consumer; never print the value.
Set Secret
use azure_security_keyvault_secrets::models::SetSecretParameters;
let params = SetSecretParameters {
value: Some("secret-value".into()),
..Default::default()
};
let secret = client
.set_secret("secret-name", params.try_into()?, None)
.await?
.into_model()?;
Update Secret Properties
use azure_security_keyvault_secrets::models::UpdateSecretPropertiesParameters;
use std::collections::HashMap;
let params = UpdateSecretPropertiesParameters {
content_type: Some("text/plain".into()),
tags: Some(HashMap::from([("env".into(), "prod".into())])),
..Default::default()
};
client
.update_secret_properties("secret-name", params.try_into()?, None)
.await?;
Delete Secret
client.delete_secret("secret-name", None).await?;
List Secrets
use azure_security_keyvault_secrets::ResourceExt;
use futures::TryStreamExt;
let mut pager = client.list_secret_properties(None)?;
while let Some(secret) = pager.try_next().await? {
let name = secret.resource_id()?.name;
println!("Secret: {}", name);
}
Get Specific Version
use azure_security_keyvault_secrets::models::SecretClientGetSecretOptions;
let options = SecretClientGetSecretOptions {
secret_version: Some("version-id".into()),
..Default::default()
};
let secret = client
.get_secret("secret-name", Some(options))
.await?
.into_model()?;
Best Practices
- Use Entra ID auth —
DeveloperToolsCredentialfor dev,ManagedIdentityCredentialfor production - Use
into_model()?— to deserialize responses - Use
ResourceExttrait — for extracting names from IDs - Handle soft delete — deleted secrets can be recovered within retention period
- Set content type — helps identify secret format
- Use tags — for organizing and filtering secrets
- Version secrets — new values create new versions automatically
RBAC Permissions
Assign these Key Vault roles:
Key Vault Secrets User— get and listKey Vault Secrets Officer— full CRUD
The reviewed example set uses azure_security_keyvault_secrets 1.0.1 and compatible Azure core/credential crates. Record and commit Cargo.lock; source/API review is not a compiler or live-service test.
Reference Links
When to Use
Use when a Rust application retrieves a specified secret/version or performs authorized secret creation, metadata updates, listing or deletion in an identified Key Vault.
Limitations
- Examples are fragments inside async application code, with compatible pinned Azure crates and the required Tokio/Serde/Futures dependencies; verify the selected version’s API before use. They were reviewed against official source/reference, not compiled or run against a cloud account here.
- Use an authorized tenant, resource and identity with least privilege. Writes, overwrites, deletes, backup retrieval and account changes require the corresponding scope; cleanup may remove only explicitly identified disposable resources. Bound requests, retries and downloaded bytes, and do not log payloads, credentials or secret values.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Networking
Design and implement Azure network infrastructure including VNets, subnets, NSGs, VNet peering, private endpoints, Azure Firewall, and Application Gateway. Covers both az CLI commands and Terraform configurations for production hub-spoke topologies.
Examples provision billable infrastructure and alter network access. Confirm tenant/subscription/region, CIDR overlap, target resources, approved exposure and rollback before mutation; inventory existing routes/rules first. These fragments are not a complete production topology.
Prerequisites
# Install Azure CLI
# Prerequisite: organization-approved Azure CLI installed from a verified signed package.
az version
# Login and set subscription
az login
az account set --subscription "my-subscription-id"
# Register required providers
az provider register --namespace Microsoft.Network
# Create resource group
az group create --name networking-rg --location eastus
VNet and Subnet Creation
Hub VNet
# Create hub VNet for shared services
az network vnet create \
--resource-group networking-rg \
--name hub-vnet \
--address-prefix 10.0.0.0/16 \
--location eastus \
--tags environment=prod role=hub
# Add subnets to hub
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name hub-vnet \
--name AzureFirewallSubnet \
--address-prefix 10.0.1.0/26
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name hub-vnet \
--name GatewaySubnet \
--address-prefix 10.0.2.0/27
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name hub-vnet \
--name SharedServicesSubnet \
--address-prefix 10.0.3.0/24
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name hub-vnet \
--name AzureBastionSubnet \
--address-prefix 10.0.4.0/26
Spoke VNet
# Create spoke VNet for application workloads
az network vnet create \
--resource-group networking-rg \
--name spoke-prod-vnet \
--address-prefix 10.1.0.0/16 \
--location eastus \
--tags environment=prod role=spoke
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name web-subnet \
--address-prefix 10.1.1.0/24
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name app-subnet \
--address-prefix 10.1.2.0/24
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name data-subnet \
--address-prefix 10.1.3.0/24 \
--private-endpoint-network-policies Enabled
# List all subnets in a VNet
az network vnet subnet list \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--output table
Network Security Groups
# Create NSG for web tier
az network nsg create \
--resource-group networking-rg \
--name web-nsg \
--tags tier=web
# Allow HTTPS from internet
az network nsg rule create \
--resource-group networking-rg \
--nsg-name web-nsg \
--name AllowHTTPS \
--priority 100 \
--direction Inbound \
--access Allow \
--protocol Tcp \
--source-address-prefixes Internet \
--destination-port-ranges 443
# Allow HTTP for redirect
az network nsg rule create \
--resource-group networking-rg \
--nsg-name web-nsg \
--name AllowHTTP \
--priority 110 \
--direction Inbound \
--access Allow \
--protocol Tcp \
--source-address-prefixes Internet \
--destination-port-ranges 80
# Deny all other inbound traffic
az network nsg rule create \
--resource-group networking-rg \
--nsg-name web-nsg \
--name DenyAllInbound \
--priority 4096 \
--direction Inbound \
--access Deny \
--protocol '*' \
--source-address-prefixes '*' \
--destination-port-ranges '*'
# Create NSG for app tier -- only allow from web subnet
az network nsg create \
--resource-group networking-rg \
--name app-nsg
az network nsg rule create \
--resource-group networking-rg \
--nsg-name app-nsg \
--name AllowFromWeb \
--priority 100 \
--direction Inbound \
--access Allow \
--protocol Tcp \
--source-address-prefixes 10.1.1.0/24 \
--destination-port-ranges 8080
# Create NSG for data tier -- only allow from app subnet
az network nsg create \
--resource-group networking-rg \
--name data-nsg
az network nsg rule create \
--resource-group networking-rg \
--nsg-name data-nsg \
--name AllowSQLFromApp \
--priority 100 \
--direction Inbound \
--access Allow \
--protocol Tcp \
--source-address-prefixes 10.1.2.0/24 \
--destination-port-ranges 1433
# Explicit deny is required for app/data isolation: default AllowVNetInBound
# otherwise permits other VNet traffic despite the narrow allow rules above.
for tier in app data; do
az network nsg rule create --resource-group networking-rg \
--nsg-name "${tier}-nsg" --name DenyOtherInbound --priority 4096 \
--direction Inbound --access Deny --protocol '*' \
--source-address-prefixes '*' --destination-port-ranges '*'
done
# Add required platform health/management exceptions before associating NSGs.
# Associate NSG with subnet
az network vnet subnet update \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name web-subnet \
--network-security-group web-nsg
az network vnet subnet update \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name app-subnet \
--network-security-group app-nsg
az network vnet subnet update \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name data-subnet \
--network-security-group data-nsg
# View effective NSG rules
az network nic list-effective-nsg \
--resource-group networking-rg \
--name myvm-nic \
--output table
VNet Peering
# Peer hub to spoke
az network vnet peering create \
--resource-group networking-rg \
--name hub-to-spoke-prod \
--vnet-name hub-vnet \
--remote-vnet spoke-prod-vnet \
--allow-vnet-access \
--allow-forwarded-traffic \
--allow-gateway-transit
# Peer spoke to hub
az network vnet peering create \
--resource-group networking-rg \
--name spoke-prod-to-hub \
--vnet-name spoke-prod-vnet \
--remote-vnet hub-vnet \
--allow-vnet-access \
--allow-forwarded-traffic \
--use-remote-gateways false
# Verify peering status
az network vnet peering list \
--resource-group networking-rg \
--vnet-name hub-vnet \
--output table
Private Endpoints
# Create private endpoint for Azure SQL
az network private-endpoint create \
--resource-group networking-rg \
--name sql-private-endpoint \
--vnet-name spoke-prod-vnet \
--subnet data-subnet \
--private-connection-resource-id "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Sql/servers/myserver" \
--group-id sqlServer \
--connection-name sql-connection
# Create private DNS zone for SQL
az network private-dns zone create \
--resource-group networking-rg \
--name privatelink.database.windows.net
# Link DNS zone to VNet
az network private-dns link vnet create \
--resource-group networking-rg \
--zone-name privatelink.database.windows.net \
--name spoke-dns-link \
--virtual-network spoke-prod-vnet \
--registration-enabled false
# Create DNS record for the private endpoint
az network private-endpoint dns-zone-group create \
--resource-group networking-rg \
--endpoint-name sql-private-endpoint \
--name sql-dns-group \
--private-dns-zone privatelink.database.windows.net \
--zone-name privatelink.database.windows.net
# Create private endpoint for Storage Account
az network private-endpoint create \
--resource-group networking-rg \
--name storage-private-endpoint \
--vnet-name spoke-prod-vnet \
--subnet data-subnet \
--private-connection-resource-id "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.Storage/storageAccounts/mystorageacct" \
--group-id blob \
--connection-name storage-blob-connection
# Create private endpoint for Key Vault
az network private-endpoint create \
--resource-group networking-rg \
--name kv-private-endpoint \
--vnet-name spoke-prod-vnet \
--subnet app-subnet \
--private-connection-resource-id "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.KeyVault/vaults/myvault" \
--group-id vault \
--connection-name kv-connection
Azure Firewall
# Create public IP for firewall
az network public-ip create \
--resource-group networking-rg \
--name fw-public-ip \
--sku Standard \
--allocation-method Static
# Create Azure Firewall
az network firewall create \
--resource-group networking-rg \
--name hub-firewall \
--location eastus \
--sku AZFW_VNet \
--tier Standard
# Configure firewall IP
az network firewall ip-config create \
--resource-group networking-rg \
--firewall-name hub-firewall \
--name fw-ipconfig \
--public-ip-address fw-public-ip \
--vnet-name hub-vnet
# Get firewall private IP for route tables
FW_PRIVATE_IP=$(az network firewall show \
--resource-group networking-rg \
--name hub-firewall \
--query "ipConfigurations[0].privateIpAddress" \
--output tsv)
# Create application rule allowing web traffic
az network firewall application-rule create \
--resource-group networking-rg \
--firewall-name hub-firewall \
--collection-name AllowWeb \
--name AllowGoogle \
--protocols Https=443 Http=80 \
--source-addresses 10.1.0.0/16 \
--target-fqdns "*.google.com" "*.microsoft.com" \
--action Allow \
--priority 100
# Create network rule for DNS
az network firewall network-rule create \
--resource-group networking-rg \
--firewall-name hub-firewall \
--collection-name AllowDNS \
--name AllowDNS \
--protocols UDP \
--source-addresses 10.1.0.0/16 \
--destination-addresses 168.63.129.16 \
--destination-ports 53 \
--action Allow \
--priority 200
# Create route table to send traffic through firewall
az network route-table create \
--resource-group networking-rg \
--name spoke-route-table
az network route-table route create \
--resource-group networking-rg \
--route-table-name spoke-route-table \
--name default-to-firewall \
--address-prefix 0.0.0.0/0 \
--next-hop-type VirtualAppliance \
--next-hop-ip-address "$FW_PRIVATE_IP"
# Associate route table with spoke subnet
az network vnet subnet update \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name app-subnet \
--route-table spoke-route-table
The private endpoints above do not automatically disable public network access. Configure and verify resource-level public access policy, private DNS zones/links/records for each service/subresource, approval state and allowed/denied-client resolution. Peering is not transitive; gateway transit requires an actual gateway and intended spoke settings. Validate return paths and effective routes before routing through the firewall.
Application Gateway with WAF
# Create public IP
az network public-ip create \
--resource-group networking-rg \
--name appgw-public-ip \
--sku Standard \
--allocation-method Static
# Create Application Gateway subnet
az network vnet subnet create \
--resource-group networking-rg \
--vnet-name spoke-prod-vnet \
--name AppGatewaySubnet \
--address-prefix 10.1.10.0/24
# HTTP-only illustrative gateway; port443 alone does not enable TLS.
# For production configure a valid certificate/Key Vault identity, HTTPS listener,
# approved TLS policy and backend TLS/health probes before exposing traffic.
# Create Application Gateway with WAF v2
az network application-gateway create \
--resource-group networking-rg \
--name myapp-appgw \
--location eastus \
--sku WAF_v2 \
--capacity 2 \
--vnet-name spoke-prod-vnet \
--subnet AppGatewaySubnet \
--public-ip-address appgw-public-ip \
--http-settings-port 80 \
--http-settings-protocol Http \
--frontend-port 80 \
--servers 10.1.2.4 10.1.2.5
# Enable WAF policy
az network application-gateway waf-policy create \
--resource-group networking-rg \
--name myapp-waf-policy
az network application-gateway waf-policy managed-rule rule-set add \
--resource-group networking-rg \
--policy-name myapp-waf-policy \
--type OWASP \
--version 3.2
# Attach the policy (creation alone does not apply it).
az network application-gateway update --resource-group networking-rg \
--name myapp-appgw --firewall-policy myapp-waf-policy
Contents
When to Use
- You are designing the network foundation for Azure workloads.
- You need to isolate environments with VNets and NSGs.
- You are connecting on-premises networks to Azure via VPN or ExpressRoute.
- You need private connectivity to PaaS services via private endpoints.
- You are implementing centralized egress filtering with Azure Firewall.
- You need to set up load balancing or application-layer routing with Application Gateway.
Limitations
- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
- Docs-only import: upstream scripts and templates not bundled.
Azure Service Bus SDK for TypeScript
Enterprise messaging with queues, topics, and subscriptions.
Installation
npm install @azure/service-bus @azure/identity
Environment Variables
SERVICEBUS_NAMESPACE=<namespace>.servicebus.windows.net
SERVICEBUS_QUEUE_NAME=my-queue
SERVICEBUS_TOPIC_NAME=my-topic
SERVICEBUS_SUBSCRIPTION_NAME=my-subscription
Authentication
import { ServiceBusClient } from "@azure/service-bus";
import { DefaultAzureCredential } from "@azure/identity";
const fullyQualifiedNamespace = process.env.SERVICEBUS_NAMESPACE!;
const client = new ServiceBusClient(fullyQualifiedNamespace, new DefaultAzureCredential());
Delivery boundaries
Examples mutate queues and independent fragments reuse names. Sending, scheduling and settling messages require authorization for the exact namespace/entity. Make business processing idempotent before completion; peek-lock can redeliver after failure. Avoid logging private bodies, renew locks where needed and close the shared client on shutdown.
Core Workflow
Send Messages to Queue
const sender = client.createSender("my-queue");
// Single message
await sender.sendMessages({
body: { orderId: "12345", amount: 99.99 },
contentType: "application/json",
});
// Batch messages
const batch = await sender.createMessageBatch();
if (!batch.tryAddMessage({ body: "Message 1" }) ||
!batch.tryAddMessage({ body: "Message 2" })) {
throw new Error("Message batch exceeds size limit; split and retry deliberately");
}
await sender.sendMessages(batch);
await sender.close();
Receive Messages from Queue
const receiver = client.createReceiver("my-queue");
// Receive batch
const messages = await receiver.receiveMessages(10, { maxWaitTimeInMs: 5000 });
for (const message of messages) {
console.log(`Received: ${message.body}`);
await receiver.completeMessage(message);
}
await receiver.close();
Subscribe to Messages (Event-Driven)
const receiver = client.createReceiver("my-queue");
const subscription = receiver.subscribe({
processMessage: async (message) => {
console.log(`Processing: ${message.body}`);
// Message auto-completed on success
},
processError: async (args) => {
console.error(`Error: ${args.error}`);
},
});
// Stop after some time
setTimeout(async () => {
await subscription.close();
await receiver.close();
}, 60000);
Topics and Subscriptions
// Send to topic
const topicSender = client.createSender("my-topic");
await topicSender.sendMessages({
body: { event: "order.created", data: { orderId: "123" } },
applicationProperties: { eventType: "order.created" },
});
// Receive from subscription
const subscriptionReceiver = client.createReceiver("my-topic", "my-subscription");
const messages = await subscriptionReceiver.receiveMessages(10);
Message Sessions
// Send session message
const sender = client.createSender("session-queue");
await sender.sendMessages({
body: { step: 1, data: "First step" },
sessionId: "workflow-123",
});
// Receive session messages
const sessionReceiver = await client.acceptSession("session-queue", "workflow-123");
const messages = await sessionReceiver.receiveMessages(10);
// Get/set session state
const state = await sessionReceiver.getSessionState();
await sessionReceiver.setSessionState(Buffer.from(JSON.stringify({ progress: 50 })));
await sessionReceiver.close();
Dead-Letter Handling
// Move to dead-letter
await receiver.deadLetterMessage(message, {
deadLetterReason: "Validation failed",
deadLetterErrorDescription: "Missing required field: orderId",
});
// Process dead-letter queue
const dlqReceiver = client.createReceiver("my-queue", { subQueueType: "deadLetter" });
const dlqMessages = await dlqReceiver.receiveMessages(10);
for (const msg of dlqMessages) {
console.log(`DLQ Reason: ${msg.deadLetterReason}`);
// Inspect and durably record the authorized recovery outcome first.
// Complete only after successful recovery; logging alone must not delete DLQ evidence.
// await dlqReceiver.completeMessage(msg);
}
Scheduled Messages
const sender = client.createSender("my-queue");
// Schedule for future delivery
const scheduledTime = new Date(Date.now() + 60000); // 1 minute from now
const sequenceNumber = await sender.scheduleMessages(
{ body: "Delayed message" },
scheduledTime
);
// Cancel scheduled message
await sender.cancelScheduledMessages(sequenceNumber);
Message Deferral
// Defer message for later
await receiver.deferMessage(message);
// Receive deferred message by sequence number
const deferredMessage = await receiver.receiveDeferredMessages(message.sequenceNumber!);
await receiver.completeMessage(deferredMessage[0]);
Peek Messages (Non-Destructive)
const receiver = client.createReceiver("my-queue");
// Peek without removing
const peekedMessages = await receiver.peekMessages(10);
for (const msg of peekedMessages) {
console.log(`Peeked: ${msg.body}`);
}
Key Types
import {
ServiceBusClient,
ServiceBusSender,
ServiceBusReceiver,
ServiceBusSessionReceiver,
ServiceBusMessage,
ServiceBusReceivedMessage,
ProcessMessageCallback,
ProcessErrorCallback,
} from "@azure/service-bus";
Receive Modes
// Peek-Lock (default) - message locked until completed/abandoned
const receiver = client.createReceiver("my-queue", { receiveMode: "peekLock" });
await receiver.completeMessage(message); // Remove from queue
await receiver.abandonMessage(message); // Return to queue
await receiver.deferMessage(message); // Defer for later
await receiver.deadLetterMessage(message); // Move to DLQ
// Receive-and-Delete - message removed immediately
const receiver = client.createReceiver("my-queue", { receiveMode: "receiveAndDelete" });
Best Practices
- Use Entra ID auth - Avoid connection strings in production
- Reuse clients - Create
ServiceBusClientonce, share across senders/receivers - Close resources - Always close senders/receivers when done
- Handle errors - Implement
processErrorcallback for subscription receivers - Use sessions for ordering - When message order matters within a group
- Configure dead-letter - Always handle DLQ messages
- Batch sends - Use
createMessageBatch()for multiple messages
Reference Documentation
For detailed patterns, see:
- Queues vs Topics Patterns - Queue/topic patterns, sessions, receive modes, message settlement
- Error Handling and Reliability - ServiceBusError codes, DLQ handling, lock renewal, graceful shutdown
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Data Lake Storage Gen2 SDK for Python
Hierarchical file system for big data analytics workloads.
Installation
pip install azure-storage-file-datalake azure-identity
Environment Variables
AZURE_STORAGE_ACCOUNT_URL=https://<account>.dfs.core.windows.net
Authentication
from azure.identity import DefaultAzureCredential
from azure.storage.filedatalake import DataLakeServiceClient
credential = DefaultAzureCredential()
account_url = "https://<account>.dfs.core.windows.net"
service_client = DataLakeServiceClient(account_url=account_url, credential=credential)
Client Hierarchy
| Client | Purpose |
|---|---|
DataLakeServiceClient | Account-level operations |
FileSystemClient | Container (file system) operations |
DataLakeDirectoryClient | Directory operations |
DataLakeFileClient | File operations |
These are independent fragments, not a run-all script. Confirm account/filesystem/path and protect existing data before writes, renames, recursive ACL changes or deletes. Never use production placeholders as cleanup targets. Bound recursive listings/download bytes and use non-overwriting local outputs. Recursive ACL updates can partially fail: inspect counters/failure details and resume only with exact scope. Close async credentials as well as clients in failure paths; upload success does not establish business correctness.
File System Operations
# Create file system (container)
file_system_client = service_client.create_file_system("myfilesystem")
# Get existing
file_system_client = service_client.get_file_system_client("myfilesystem")
# Delete
service_client.delete_file_system("myfilesystem")
# List file systems
for fs in service_client.list_file_systems():
print(fs.name)
Directory Operations
file_system_client = service_client.get_file_system_client("myfilesystem")
# Create directory
directory_client = file_system_client.create_directory("mydir")
# Create nested directories
directory_client = file_system_client.create_directory("path/to/nested/dir")
# Get directory client
directory_client = file_system_client.get_directory_client("mydir")
# Delete directory
directory_client.delete_directory()
# Rename/move directory
directory_client.rename_directory(new_name="myfilesystem/newname")
File Operations
Upload File
# Get file client
file_client = file_system_client.get_file_client("path/to/file.txt")
# Upload from local file
with open("local-file.txt", "rb") as data:
file_client.upload_data(data, overwrite=False)
# Upload bytes
file_client.upload_data(b"Hello, Data Lake!", overwrite=False)
# Separate append example: create an explicitly new empty file first.
file_client = file_system_client.create_file("disposable-append-example.txt")
file_client.append_data(data=b"chunk1", offset=0, length=6)
file_client.append_data(data=b"chunk2", offset=6, length=6)
file_client.flush_data(12) # Commit the data
Download File
file_client = file_system_client.get_file_client("path/to/file.txt")
# Download all content
download = file_client.download_file()
content = download.readall()
# Download to file
with open("downloaded.txt", "wb") as f:
download = file_client.download_file()
download.readinto(f)
# Download range
download = file_client.download_file(offset=0, length=100)
Delete File
file_client.delete_file()
List Contents
# List paths (files and directories)
for path in file_system_client.get_paths():
print(f"{'DIR' if path.is_directory else 'FILE'}: {path.name}")
# List paths in directory
for path in file_system_client.get_paths(path="mydir"):
print(path.name)
# Recursive listing
for path in file_system_client.get_paths(path="mydir", recursive=True):
print(path.name)
File/Directory Properties
# Get properties
properties = file_client.get_file_properties()
print(f"Size: {properties.size}")
print(f"Last modified: {properties.last_modified}")
# Set metadata
file_client.set_metadata(metadata={"processed": "true"})
Access Control (ACL)
# Get ACL
acl = directory_client.get_access_control()
print(f"Owner: {acl['owner']}")
print(f"Permissions: {acl['permissions']}")
# Set ACL
directory_client.set_access_control(
owner="user-id",
permissions="rwxr-x---"
)
# Update ACL entries
from azure.storage.filedatalake import AccessControlChangeResult
directory_client.update_access_control_recursive(
acl="user:user-id:rwx"
)
Async Client
from azure.storage.filedatalake.aio import DataLakeServiceClient
from azure.identity.aio import DefaultAzureCredential
async def datalake_operations():
credential = DefaultAzureCredential()
async with DataLakeServiceClient(
account_url="https://<account>.dfs.core.windows.net",
credential=credential
) as service_client:
file_system_client = service_client.get_file_system_client("myfilesystem")
file_client = file_system_client.get_file_client("test.txt")
await file_client.upload_data(b"async content", overwrite=False)
download = await file_client.download_file()
content = await download.readall()
import asyncio
asyncio.run(datalake_operations())
Best Practices
- Use hierarchical namespace for file system semantics
- Use
append_data+flush_datafor large file uploads - Review ACL scope: default ACLs affect new descendants; existing descendants require a separately authorized recursive operation
- Use async client for high-throughput scenarios
- Use
get_pathswithrecursive=Truefor full directory listing - Set metadata for custom file attributes
- Consider Blob API for simple object storage use cases
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Azure Queue Storage library for Rust
When to Use
Use this skill when you need azure Queue Storage library for Rust. Send, receive, and manage queue messages. Triggers: "queue storage rust", "QueueClient rust", "send message rust", "receive messages rust", "QueueServiceClient rust", "queue rust".
Client library for Azure Queue Storage — send, receive, and manage queue messages.
Use this skill when:
- An app needs to send or receive messages from Azure Queue Storage in Rust
- You need to create or manage queues
- You need to peek, receive, or delete queue messages
- You need RBAC-based auth for queue operations
IMPORTANT: Only use the official
azure_storage_queuecrate published by the azure-sdk crates.io user. Do NOT use unofficial or community crates. Official crates use underscores in names and none have version 0.21.0.
Installation
cargo add azure_storage_queue azure_identity azure_core tokio
If your code uses
azure_coretypes directly, addazure_coretoCargo.toml. If you only useazure_storage_queuere-exports, directazure_coredependency is optional.
Environment Variables
AZURE_STORAGE_QUEUE_ENDPOINT=https://<account>.queue.core.windows.net/ # Required for all operations
Authentication
use azure_core::http::Url;
use azure_identity::DeveloperToolsCredential;
use azure_storage_queue::QueueServiceClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// Local dev: DeveloperToolsCredential. Production: use ManagedIdentityCredential.
let credential = DeveloperToolsCredential::new(None)?;
let service_url = Url::parse("https://<storage_account_name>.queue.core.windows.net/")?;
let service_client = QueueServiceClient::new(service_url, Some(credential), None)?;
// Derive a queue client by name.
let queue_client = service_client.queue_client("<queue_name>")?;
Ok(())
}
Client Types
| Client | Purpose | Access |
|---|---|---|
QueueServiceClient | Account-level operations, list queues | QueueServiceClient::new() |
QueueClient | Queue operations, send/receive/delete | service_client.queue_client("<name>")? |
Core Workflow
Send a Message
use azure_core::http::Url;
use azure_identity::DeveloperToolsCredential;
use azure_storage_queue::{models::QueueMessage, QueueServiceClient};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let credential = DeveloperToolsCredential::new(None)?;
let service_url = Url::parse("https://<storage_account_name>.queue.core.windows.net/")?;
let service_client = QueueServiceClient::new(service_url, Some(credential), None)?;
let queue_client = service_client.queue_client("<queue_name>")?;
let message = QueueMessage {
message_text: Some("hello world".to_string()),
};
queue_client.send_message(message.try_into()?, None).await?;
Ok(())
}
Receive Messages
use azure_core::http::Url;
use azure_identity::DeveloperToolsCredential;
use azure_storage_queue::QueueServiceClient;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let credential = DeveloperToolsCredential::new(None)?;
let service_url = Url::parse("https://<storage_account_name>.queue.core.windows.net/")?;
let service_client = QueueServiceClient::new(service_url, Some(credential), None)?;
let queue_client = service_client.queue_client("<queue_name>")?;
let response = queue_client.receive_messages(None).await?;
let messages = response.into_model()?;
for msg in messages.items.unwrap_or_default() {
println!("{}", msg.message_text.as_deref().unwrap_or("<empty>"));
}
Ok(())
}
Delete a Message
After receiving a message, delete it using the message ID and pop receipt:
let response = queue_client.receive_messages(None).await?;
let messages = response.into_model()?;
for msg in messages.items.unwrap_or_default() {
if let (Some(id), Some(pop_receipt)) = (&msg.message_id, &msg.pop_receipt) {
queue_client.delete_message(id, pop_receipt, None).await?;
}
}
Peek Messages
Peek at messages without removing them from the queue:
let response = queue_client.peek_messages(None).await?;
let messages = response.into_model()?;
for msg in messages.items.unwrap_or_default() {
println!("Peeked: {}", msg.message_text.as_deref().unwrap_or("<empty>"));
}
RBAC Roles
For Entra ID auth, assign one of these roles to the identity:
| Role | Access |
|---|---|
Storage Queue Data Reader | Read and peek messages |
Storage Queue Data Contributor | Read/write messages |
Storage Queue Data Message Sender | Send messages only |
Storage Queue Data Message Processor | Receive and delete |
Best Practices
- Use
cargo addto manage dependencies, never editCargo.tomldirectly. Add and remove Rust SDK dependencies with cargo commands instead of manual manifest edits. - Add
azure_coreonly when importingazure_coretypes directly. If your code importsazure_core::http::Url,azure_core::http::RequestContent, orazure_core::error::ErrorKind, includeazure_core; otherwise a direct dependency is optional. - Use
DeveloperToolsCredentialfor local dev,ManagedIdentityCredentialfor production — Rust does not provide a singleDefaultAzureCredentialtype - Never hardcode credentials — use environment variables or managed identity
- Assign RBAC roles — ensure appropriate queue data roles for the identity
- Use
QueueServiceClientas the entry point and deriveQueueClientfrom it viaqueue_client() - Delete messages after processing — use the message ID and pop receipt from
receive_messages - Reuse clients — clients are thread-safe; create once, share across tasks
Reference Links
| Resource | Link |
|---|---|
| API Reference | https://docs.rs/crate/azure_storage_queue/latest |
| crates.io | https://crates.io/crates/azure_storage_queue |
| Source Code | https://github.com/Azure/azure-sdk-for-rust/tree/main/sdk/storage/azure_storage_queue |
Limitations
- Use this skill only when the task clearly matches its upstream source and local project context.
- Verify commands, generated code, dependencies, credentials, and external service behavior before applying changes.
- Do not treat examples as a substitute for environment-specific tests, security review, or user approval for destructive or costly actions.
Queue delivery can repeat. Make processing idempotent, extend visibility only within a bounded policy and delete a message only after the intended durable effect succeeds. A received message is not completed work; handle poison messages and expired pop receipts explicitly. Pin compatible crate versions and enable the Tokio runtime/macro features required by the chosen example.
@azure/storage-queue (TypeScript/JavaScript)
SDK for Azure Queue Storage operations — send, receive, peek, and manage messages in queues.
Detailed Guide
Read the detailed guide before executing this skill. It retains the complete procedure and reference material. Treat its safety, prerequisites, and validation requirements as mandatory. For focused work, load the relevant sections; for end-to-end work, read the guide completely.
When to Use
This skill is applicable to execute the workflow or actions described in the overview.
Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
Cloudflare Workers
Deploy JavaScript and TypeScript functions to Cloudflare's global edge network with sub-millisecond cold starts.
When to Use
- Building lightweight APIs and microservices at the edge.
- Adding middleware (auth, rate limiting, header injection) in front of origin servers.
- Running cron jobs on a schedule without maintaining infrastructure.
- Processing webhooks, image transformations, or A/B testing logic.
- Serving dynamic content from KV, D1, or R2 storage bindings.
Prerequisites
- Node.js 18+ installed locally.
- Wrangler CLI:
npm install -g wrangler. - Cloudflare account (free plan supports 100,000 requests/day).
- Authenticated:
wrangler loginor setCLOUDFLARE_API_TOKEN.
Verify Node/Wrangler support, plan quotas and CPU limits for the actual account; historical numbers below are not current entitlement guarantees. Choose target account/environment/routes explicitly before deploy, rollback or remote dev. KV read-modify-write is non-atomic and eventually consistent; concurrent increments lose updates, repeated puts hit write limits, and TTL resets make this a sliding approximation. Use an authoritative rate limiter for security. Increasing cacheTtl does not make KV strongly consistent. waitUntil is bounded background work, not a durable job queue and does not bypass CPU limits. Bind only approved origins, strip unexpected credentials before proxying and validate incoming data before analytics egress. Inline KV/D1 examples mutate on every request and must be isolated or authenticated. Scheduled helpers and analytics endpoints are placeholders, the third cron has no handler, and the Durable Object class must be re-exported from the configured entrypoint with a compatible migration type.
Quick Start
# Scaffold a new Worker project
npm create cloudflare@latest my-worker
cd my-worker
# Login to Cloudflare
npx wrangler login
# Start local development server (port 8787)
npx wrangler dev
# Deploy to production
npx wrangler deploy
Essential Wrangler Commands
# Remote development: executes in Cloudflare and can affect bound remote resources
npx wrangler dev --remote
# Deploy to a specific environment
npx wrangler deploy --env staging
# Set a secret (prompts for value)
npx wrangler secret put API_TOKEN
npx wrangler secret put API_TOKEN --env staging
# List secrets
npx wrangler secret list
# Tail production logs in real time
npx wrangler tail
# Tail with filters
npx wrangler tail --status=error --search="timeout"
# View deployment versions
npx wrangler deployments list
# Rollback to a previous deployment
npx wrangler rollback
Wrangler Configuration
# wrangler.toml
name = "my-api"
main = "src/index.ts"
compatibility_date = "2024-09-01"
compatibility_flags = ["nodejs_compat"]
# Custom routes
routes = [
{ pattern = "api.example.com/*", zone_name = "example.com" }
]
# Or use a workers.dev subdomain
# workers_dev = true
# Environment variables (non-secret)
[vars]
ENVIRONMENT = "production"
API_VERSION = "v2"
# Staging environment override
[env.staging]
name = "my-api-staging"
routes = [
{ pattern = "api-staging.example.com/*", zone_name = "example.com" }
]
[env.staging.vars]
ENVIRONMENT = "staging"
Worker Examples
Basic API Router
// src/index.ts
export interface Env {
ENVIRONMENT: string;
}
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
const url = new URL(request.url);
switch (url.pathname) {
case "/":
return new Response("OK", { status: 200 });
case "/api/health":
return Response.json({
status: "healthy",
env: env.ENVIRONMENT,
timestamp: new Date().toISOString(),
});
case "/api/data":
if (request.method !== "POST") {
return new Response("Method Not Allowed", { status: 405 });
}
const body = await request.json();
// Process in the background after returning response
ctx.waitUntil(logToAnalytics(body));
return Response.json({ received: true });
default:
return new Response("Not Found", { status: 404 });
}
},
};
async function logToAnalytics(data: unknown): Promise<void> {
await fetch("https://analytics.example.com/ingest", {
method: "POST",
body: JSON.stringify(data),
headers: { "Content-Type": "application/json" },
});
}
Approximate KV Counter (not an enforcement-grade rate limiter)
// src/rate-limiter.ts
interface Env {
RATE_LIMIT_KV: KVNamespace;
ORIGIN_URL: string;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const ip = request.headers.get("CF-Connecting-IP") || "unknown";
const key = `ratelimit:${ip}`;
const window = 60; // seconds
const maxRequests = 100;
const current = parseInt((await env.RATE_LIMIT_KV.get(key)) || "0");
if (current >= maxRequests) {
return new Response("Too Many Requests", {
status: 429,
headers: { "Retry-After": String(window) },
});
}
await env.RATE_LIMIT_KV.put(key, String(current + 1), {
expirationTtl: window,
});
// Forward to origin
const originRequest = new Request(new URL(new URL(request.url).pathname + new URL(request.url).search, env.ORIGIN_URL), request);
return fetch(originRequest);
},
};
KV Storage Binding
# wrangler.toml
[[kv_namespaces]]
binding = "MY_KV"
id = "abc123def456"
# Optional preview namespace on the same binding:
# preview_id = "preview789"
// KV operations in a Worker
interface Env {
MY_KV: KVNamespace;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Write with TTL
await env.MY_KV.put("session:abc", JSON.stringify({ user: "alice" }), {
expirationTtl: 3600,
});
// Read
const session = await env.MY_KV.get("session:abc", "json");
// List keys by prefix
const list = await env.MY_KV.list({ prefix: "session:", limit: 100 });
// Delete
await env.MY_KV.delete("session:abc");
return Response.json({ session, keys: list.keys.length });
},
};
# KV CLI operations
npx wrangler kv namespace create MY_KV
npx wrangler kv namespace list
npx wrangler kv key put --namespace-id=abc123 "config:feature-flags" '{"darkMode":true}'
npx wrangler kv key get --namespace-id=abc123 "config:feature-flags"
npx wrangler kv key list --namespace-id=abc123 --prefix="config:"
D1 Database Binding
# wrangler.toml
[[d1_databases]]
binding = "DB"
database_name = "my-app"
database_id = "xxxx-yyyy-zzzz"
// D1 SQL queries in a Worker
interface Env {
DB: D1Database;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
// Parameterized query
const { results } = await env.DB.prepare(
"SELECT id, name, email FROM users WHERE active = ? LIMIT ?"
)
.bind(1, 50)
.all();
// Insert
await env.DB.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
.bind("Alice", "alice@example.com")
.run();
// Batch multiple statements
await env.DB.batch([
env.DB.prepare("UPDATE users SET active = 0 WHERE last_login < ?").bind("2024-01-01"),
env.DB.prepare("DELETE FROM sessions WHERE expires_at < ?").bind(Date.now()),
]);
return Response.json(results);
},
};
# D1 CLI operations
npx wrangler d1 create my-app
npx wrangler d1 list
npx wrangler d1 execute my-app --command="CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT, email TEXT, active INTEGER DEFAULT 1)"
npx wrangler d1 execute my-app --file=./migrations/001_init.sql
npx wrangler d1 execute my-app --command="SELECT * FROM users" --json
Cron Triggers
# wrangler.toml
[triggers]
crons = [
"0 */6 * * *", # Every 6 hours
"0 0 * * MON", # Every Monday at midnight
"*/15 * * * *", # Every 15 minutes
]
// src/index.ts — scheduled handler
export default {
async scheduled(event: ScheduledEvent, env: Env, ctx: ExecutionContext): Promise<void> {
switch (event.cron) {
case "0 */6 * * *":
ctx.waitUntil(cleanupExpiredSessions(env));
break;
case "0 0 * * MON":
ctx.waitUntil(generateWeeklyReport(env));
break;
}
},
async fetch(request: Request, env: Env): Promise<Response> {
return new Response("OK");
},
};
Durable Objects
# wrangler.toml
[durable_objects]
bindings = [
{ name = "COUNTER", class_name = "Counter" }
]
[[migrations]]
tag = "v1"
new_classes = ["Counter"]
// src/counter.ts — Durable Object class
export class Counter {
state: DurableObjectState;
constructor(state: DurableObjectState) {
this.state = state;
}
async fetch(request: Request): Promise<Response> {
let count = (await this.state.storage.get<number>("count")) || 0;
count++;
await this.state.storage.put("count", count);
return Response.json({ count });
}
}
// src/index.ts — route to Durable Object
interface Env {
COUNTER: DurableObjectNamespace;
}
export default {
async fetch(request: Request, env: Env): Promise<Response> {
const id = env.COUNTER.idFromName("global-counter");
const stub = env.COUNTER.get(id);
return stub.fetch(request);
},
};
Custom Routing
# Route to specific zones
routes = [
{ pattern = "api.example.com/v1/*", zone_name = "example.com" },
{ pattern = "api.example.com/v2/*", zone_name = "example.com" },
]
# Or use custom domains (automatic SSL)
# Dashboard: Workers > your-worker > Triggers > Custom Domains
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
Error 1101: Worker threw exception | Unhandled error in fetch handler | Wrap handler in try/catch; check wrangler tail for stack trace |
exceeded CPU time limit | Worker exceeds 10ms CPU (free) or 30s (paid) | Optimize code; offload work with ctx.waitUntil() |
| KV reads return stale data | KV is eventually consistent (~60s) | Use cacheTtl option or switch to Durable Objects for strong consistency |
wrangler dev binding errors | Local bindings not configured | Use --remote flag or configure preview_id in wrangler.toml |
| Secret not found in Worker | Secret set for wrong environment | Verify with wrangler secret list --env <env> |
| CORS errors from browser | Missing CORS headers in response | Add Access-Control-Allow-Origin headers; handle OPTIONS preflight |
| Route not matching | Pattern does not include /* suffix | Add /* to catch all paths: api.example.com/* |
Related Skills
- cloudflare-pages (
cloudflare-pages) - Frontend deployments with Pages Functions - cloudflare-r2 (
cloudflare-r2) - Object storage at the edge - cloudflare-zero-trust (
cloudflare-zero-trust) - Protect Worker endpoints with Access
Limitations
- Infrastructure commands can disrupt services: confirm target host/scope and have backups/snapshots before mutating state.
- Docs-only import: upstream scripts and templates not bundled.
Cloud Cost Optimization
Strategies and patterns for optimizing cloud costs across AWS, Azure, GCP, and OCI.
Purpose
Implement systematic cost optimization strategies to reduce cloud spending while maintaining performance and reliability.
When to Use
- Reduce cloud spending
- Right-size resources
- Implement cost governance
- Optimize multi-cloud costs
- Meet budget constraints
Cost Optimization Framework
1. Visibility
- Implement cost allocation tags
- Use cloud cost management tools
- Set up budget alerts
- Create cost dashboards
2. Right-Sizing
- Analyze resource utilization
- Downsize over-provisioned resources
- Use auto-scaling
- Remove idle resources
3. Pricing Models
- Use reserved capacity
- Leverage spot/preemptible instances
- Implement savings plans
- Use committed use discounts
4. Architecture Optimization
- Use managed services
- Implement caching
- Optimize data transfer
- Use lifecycle policies
AWS Cost Optimization
Reserved Instances
Savings: 30-72% vs On-Demand
Term: 1 or 3 years
Payment: All/Partial/No upfront
Flexibility: Standard or Convertible
Savings Plans
Compute Savings Plans: 66% savings
EC2 Instance Savings Plans: 72% savings
Applies to: EC2, Fargate, Lambda
Flexible across: Instance families, regions, OS
Spot Instances
Savings: Up to 90% vs On-Demand
Best for: Batch jobs, CI/CD, stateless workloads
Risk: 2-minute interruption notice
Strategy: Mix with On-Demand for resilience
S3 Cost Optimization
resource "aws_s3_bucket_lifecycle_configuration" "example" {
bucket = aws_s3_bucket.example.id
rule {
id = "transition-to-ia"
status = "Enabled"
transition {
days = 30
storage_class = "STANDARD_IA"
}
transition {
days = 90
storage_class = "GLACIER"
}
expiration {
days = 365
}
}
}
Azure Cost Optimization
Reserved VM Instances
- 1 or 3 year terms
- Up to 72% savings
- Flexible sizing
- Exchangeable
Azure Hybrid Benefit
- Use existing Windows Server licenses
- Up to 80% savings with RI
- Available for Windows and SQL Server
Azure Advisor Recommendations
- Right-size VMs
- Delete unused resources
- Use reserved capacity
- Optimize storage
GCP Cost Optimization
Committed Use Discounts
- 1 or 3 year commitment
- Up to 57% savings
- Applies to vCPUs and memory
- Resource-based or spend-based
Sustained Use Discounts
- Automatic discounts
- Up to 30% for running instances
- No commitment required
- Applies to Compute Engine, GKE
Preemptible VMs
- Up to 80% savings
- 24-hour maximum runtime
- Best for batch workloads
OCI Cost Optimization
Flexible Shapes
- Scale OCPUs and memory independently
- Match instance sizing to workload demand
- Reduce wasted capacity from fixed VM shapes
Commitments and Budgets
- Use annual commitments for predictable spend
- Set compartment-level budgets with alerts
- Track monthly forecasts with OCI Cost Analysis
Preemptible Capacity
- Use preemptible instances for batch and ephemeral workloads
- Keep interruption-tolerant autoscaling groups
- Mix with standard capacity for critical services
Tagging Strategy
AWS Tagging
locals {
common_tags = {
Environment = "production"
Project = "my-project"
CostCenter = "engineering"
Owner = "team@example.com"
ManagedBy = "terraform"
}
}
resource "aws_instance" "example" {
ami = "ami-12345678"
instance_type = "t3.medium"
tags = merge(
local.common_tags,
{
Name = "web-server"
}
)
}
Reference: See references/tagging-standards.md
Cost Monitoring
Budget Alerts
# AWS Budget
resource "aws_budgets_budget" "monthly" {
name = "monthly-budget"
budget_type = "COST"
limit_amount = "1000"
limit_unit = "USD"
time_period_start = "2024-01-01_00:00"
time_unit = "MONTHLY"
notification {
comparison_operator = "GREATER_THAN"
threshold = 80
threshold_type = "PERCENTAGE"
notification_type = "ACTUAL"
subscriber_email_addresses = ["team@example.com"]
}
}
Cost Anomaly Detection
- AWS Cost Anomaly Detection
- Azure Cost Management alerts
- GCP Budget alerts
- OCI Budgets and Cost Analysis
Architecture Patterns
Pattern 1: Serverless First
- Use Lambda/Functions for event-driven
- Pay only for execution time
- Auto-scaling included
- No idle costs
Pattern 2: Right-Sized Databases
Development: t3.small RDS
Staging: t3.large RDS
Production: r6g.2xlarge RDS with read replicas
Pattern 3: Multi-Tier Storage
Hot data: S3 Standard
Warm data: S3 Standard-IA (30 days)
Cold data: S3 Glacier (90 days)
Archive: S3 Deep Archive (365 days)
Pattern 4: Auto-Scaling
resource "aws_autoscaling_policy" "scale_up" {
name = "scale-up"
scaling_adjustment = 2
adjustment_type = "ChangeInCapacity"
cooldown = 300
autoscaling_group_name = aws_autoscaling_group.main.name
}
resource "aws_cloudwatch_metric_alarm" "cpu_high" {
alarm_name = "cpu-high"
comparison_operator = "GreaterThanThreshold"
evaluation_periods = "2"
metric_name = "CPUUtilization"
namespace = "AWS/EC2"
period = "60"
statistic = "Average"
threshold = "80"
alarm_actions = [aws_autoscaling_policy.scale_up.arn]
}
Cost Optimization Checklist
- Implement cost allocation tags
- Delete unused resources (EBS, EIPs, snapshots)
- Right-size instances based on utilization
- Use reserved capacity for steady workloads
- Implement auto-scaling
- Optimize storage classes
- Use lifecycle policies
- Enable cost anomaly detection
- Set budget alerts
- Review costs weekly
- Use spot/preemptible instances
- Optimize data transfer costs
- Implement caching layers
- Use managed services
- Monitor and optimize continuously
Tools
- AWS: Cost Explorer, Cost Anomaly Detection, Compute Optimizer
- Azure: Cost Management, Advisor
- GCP: Cost Management, Recommender
- OCI: Cost Analysis, Budgets, Cloud Advisor
- Multi-cloud: CloudHealth, Cloudability, Kubecost
Related Skills
terraform-module-library- For resource provisioningmulti-cloud-architecture- For cloud selection
DropTheHassle publish
External tool prerequisite
Use only an already installed tool whose exact version, complete dependency tree and integrity have been reviewed. This skill does not bootstrap tools or activate external plugins. If the prerequisite is missing, stop that executable path and report it; continue with static analysis when possible. A separate installation task must pin immutable artifacts, stage them outside active agent directories with lifecycle scripts disabled, inspect every bundled file and executable entry point (including tests and hooks), and obtain approval before activation or host configuration changes. Do not substitute a same-named workspace script or fetch a moving branch.
Overview
DropTheHassle (https://dropthehassle.com) hosts finished static files (HTML, CSS, JS, images) on a
free name.dropthehassle.app link with HTTPS, and can later put the same site on a real domain
with no DNS editing. A first deploy needs no account: it returns a live URL and a claim link. This
skill makes the agent check that the folder is a finished build, deploy it with the CLI or MCP
server, give the human the claim link, and verify the site is live. No DropTheHassle tool can pay,
and the agent must never try to. Adapted from the official skill, which also ships a local
preflight script and longer references: https://github.com/bosmdavid-gif/dropthehassle-skill
When to Use This Skill
- Use when the user asks to publish, deploy, host or share a site they built with an AI tool and wants DropTheHassle, or wants it on a free link or their own domain without DNS work and has not picked another host.
- Use when the folder is static output: a hand-written
index.html, or a Vite, Astro, Create React App, Nuxt generate, Next.jsoutput: 'export'or TanStack Start SPA build. - Do not use for apps that need a server at runtime (SSR, API routes, server functions, PHP). Say that DropTheHassle only hosts static files.
How It Works
Step 1: Find the finished folder
- Plain folder with
index.htmlat the top: that is the site. - Project with a
buildscript or avite.config.*,next.config.*,astro.config.*ornuxt.config.*: look forindex.htmlindist/,build/,out/or.output/public/. If there is none, install with the lockfile's package manager and run the build first. Next.js needsoutput: 'export'(writesout/). - An
index.htmlthat loads/src/main.tsxor another.ts,.tsx,.jsxor/src/script is a dev entry. Build it. - The DropTheHassle CLI and MCP server never run the build. On unbuilt source they stop and print the build command.
Step 2: Check the limits
Before the site is claimed: 25 MB and 1,000 files, and no executables or archives
(.exe .msi .apk .dmg .scr .bat .zip .rar .7z .iso). Signed in: 100 MB and 5,000 files. One
network can create 5 new unclaimed sites per hour and 20 per day. node_modules, .git and
hidden files are left out, except .well-known.
Step 3: Deploy
CLI, run on the project folder after the build (or on the plain site folder):
dropthehassle deploy .
It prints the live URL and a claim link, and writes .dropthehassle.json in that folder so the
next deploy from it updates the same site. That file holds the site's key: keep it out of git.
--login puts the site on the human's account after a browser approval; --slug name only works
with --login; --code XXXX-XXXX uses a 15-minute dashboard code for an existing site.
MCP, in Claude Code:
claude mcp add dropthehassle -- dropthehassle-mcp
Then call deploy_site with folder set to the absolute path. The hosted connector
https://dropthehassle.com/mcp cannot read the disk: send files inline as
{path, content, encoding} (utf8 or base64). Account tools need the human's token from
dropthehassle.com, menu, Connect your AI, set as DTH_TOKEN by the human in their own config.
Step 4: Hand over and verify
Tell the human the live URL and the claim link, and that the claim link works for 7 days. An unclaimed site can be removed after that. Then check:
curl -s "https://dropthehassle.com/api/v1/check?host=NAME.dropthehassle.app"
outcome should be live and secure true. The same check is on
https://dropthehassle.com/is-my-website-down.
Step 5: Domains, only if asked
Check names with the MCP search_domain tool or
curl -s "https://dropthehassle.com/api/v1/domains/search?q=NAME.com", and report only names the
answer marks available, with the price it returned. Buying is the human's step: after they claim
the site, get_checkout_link returns a checkout.stripe.com link for them to open and pay.
Examples
Example 1: Vite project
User: Put this site online.
Agent: No dist/ yet, so runs npm install && npm run build, then dropthehassle deploy .
Reports: Live at https://yourname.dropthehassle.app, plus the claim link (7 days).
Runs the live check: outcome "live", secure true.
Example 2: Domain search
User: Is there a .com for it?
Agent: Checks three names with search_domain, lists the available ones with the returned price,
and asks which one they want. It does not create a payment link until they say so.
Best Practices
- ✅ Deploy the build output, not the source, and rebuild before every redeploy.
- ✅ Run the CLI on the project folder so a rebuild of
dist/does not delete the link file. - ✅ Give the human the claim link word for word, with the 7-day note.
- ❌ Do not open, fill in or pay a payment link. A DropTheHassle payment link is always on
checkout.stripe.com. - ❌ Do not invent or commit a token, and do not loop new anonymous deploys.
- ❌ Do not rename the free link (
choose_link) without an explicit yes for that exact name.
Limitations
- Static files only. Server code does not run; a separate HTTPS backend can be linked with the
set_backendtool (account token). npx dropthehassle statusandrollbackneed a folder linked with--loginor--code.- On npm
dropthehassle-mcp0.4.2,search_domainneeds a token; the hosted connector and the HTTP route above work without one. - Cloud sandboxes (Claude Code on the web, Codex cloud) block dropthehassle.com by default: allow the domain or use the hosted connector.
- A plain deploy from a fresh machine creates a new site. Updating a claimed site needs a dashboard code or the token.
Security & Safety Notes
- Deploying publishes the folder on a public URL. Confirm the folder holds only what the user wants
public. Hidden files such as
.envare left out, but secrets in JS bundles are not. .dropthehassle.jsoncontains a site key. Never commit or publish it.- The account token can deploy and create payment links but cannot pay. The human sets it in their own MCP config; the agent should not ask for it in chat.
- Never buy anything or create a payment link without the user asking.
Multi-Cloud Architecture
Decision framework and patterns for architecting applications across AWS, Azure, GCP, and OCI.
Purpose
Design cloud-agnostic architectures and make informed decisions about service selection across cloud providers.
When to Use
- Design multi-cloud strategies
- Migrate between cloud providers
- Select cloud services for specific workloads
- Implement cloud-agnostic architectures
- Optimize costs across providers
Cloud Service Comparison
Compute Services
| AWS | Azure | GCP | OCI | Use Case |
|---|---|---|---|---|
| EC2 | Virtual Machines | Compute Engine | Compute | IaaS VMs |
| ECS | Container Instances | Cloud Run | Container Instances | Containers |
| EKS | AKS | GKE | OKE | Kubernetes |
| Lambda | Functions | Cloud Functions | Functions | Serverless |
| Fargate | Container Apps | Cloud Run | Container Instances | Managed containers |
Storage Services
| AWS | Azure | GCP | OCI | Use Case |
|---|---|---|---|---|
| S3 | Blob Storage | Cloud Storage | Object Storage | Object storage |
| EBS | Managed Disks | Persistent Disk | Block Volumes | Block storage |
| EFS | Azure Files | Filestore | File Storage | File storage |
| Glacier | Archive Storage | Archive Storage | Archive Storage | Cold storage |
Database Services
| AWS | Azure | GCP | OCI | Use Case |
|---|---|---|---|---|
| RDS | SQL Database | Cloud SQL | MySQL HeatWave | Managed SQL |
| DynamoDB | Cosmos DB | Firestore | NoSQL Database | NoSQL |
| Aurora | PostgreSQL/MySQL | Cloud Spanner | Autonomous Database | Distributed SQL |
| ElastiCache | Cache for Redis | Memorystore | OCI Cache | Caching |
Reference: See references/service-comparison.md for complete comparison
Multi-Cloud Patterns
Pattern 1: Single Provider with DR
- Primary workload in one cloud
- Disaster recovery in another
- Database replication across clouds
- Automated failover
Pattern 2: Best-of-Breed
- Use best service from each provider
- AI/ML on GCP
- Enterprise apps on Azure
- Regulated data platforms on OCI
- General compute on AWS
Pattern 3: Geographic Distribution
- Serve users from nearest cloud region
- Data sovereignty compliance
- Global load balancing
- Regional failover
Pattern 4: Cloud-Agnostic Abstraction
- Kubernetes for compute
- PostgreSQL for database
- S3-compatible storage (MinIO)
- Open source tools
Cloud-Agnostic Architecture
Use Cloud-Native Alternatives
- Compute: Kubernetes (EKS/AKS/GKE/OKE)
- Database: PostgreSQL/MySQL (RDS/SQL Database/Cloud SQL/MySQL HeatWave)
- Message Queue: Apache Kafka or managed streaming (MSK/Event Hubs/Confluent/OCI Streaming)
- Cache: Redis (ElastiCache/Azure Cache/Memorystore/OCI Cache)
- Object Storage: S3-compatible API
- Monitoring: Prometheus/Grafana
- Service Mesh: Istio/Linkerd
Abstraction Layers
Application Layer
↓
Infrastructure Abstraction (Terraform)
↓
Cloud Provider APIs
↓
AWS / Azure / GCP / OCI
Cost Comparison
Compute Pricing Factors
- AWS: On-demand, Reserved, Spot, Savings Plans
- Azure: Pay-as-you-go, Reserved, Spot
- GCP: On-demand, Committed use, Preemptible
- OCI: Pay-as-you-go, annual commitments, burstable/flexible shapes, preemptible instances
Cost Optimization Strategies
- Use reserved/committed capacity (30-70% savings)
- Leverage spot/preemptible instances
- Right-size resources
- Use serverless for variable workloads
- Optimize data transfer costs
- Implement lifecycle policies
- Use cost allocation tags
- Monitor with cloud cost tools
Reference: See references/multi-cloud-patterns.md
Migration Strategy
Phase 1: Assessment
- Inventory current infrastructure
- Identify dependencies
- Assess cloud compatibility
- Estimate costs
Phase 2: Pilot
- Select pilot workload
- Implement in target cloud
- Test thoroughly
- Document learnings
Phase 3: Migration
- Migrate workloads incrementally
- Maintain dual-run period
- Monitor performance
- Validate functionality
Phase 4: Optimization
- Right-size resources
- Implement cloud-native services
- Optimize costs
- Enhance security
Best Practices
- Use infrastructure as code (Terraform/OpenTofu)
- Implement CI/CD pipelines for deployments
- Design for failure across clouds
- Use managed services when possible
- Implement comprehensive monitoring
- Automate cost optimization
- Follow security best practices
- Document cloud-specific configurations
- Test disaster recovery procedures
- Train teams on multiple clouds
Related Skills
terraform-module-library- For IaC implementationcost-optimization- For cost managementhybrid-cloud-networking- For connectivity
Sponsors
Details
- Marketplace
- marslanalvi/SkillsStack
- Source
- plugins/devops/cloud
- Category
- Devops
- Keywords
- devops, cloud
More from marslanalvi/SkillsStack
All 45- devops-containers-kubernetesv1.0.0
- devops-infrastructure-networkingv1.0.0
- devops-observability-srev1.0.0
- engineering-architecture-apiv1.0.0
- engineering-code-review-qualityv1.0.0
- engineering-databasesv1.0.0
- engineering-debuggingv1.0.0
- engineering-dev-workflowv1.0.0
- engineering-frontendv1.0.0
- engineering-game-developmentv1.0.0
- engineering-git-githubv1.0.0
- engineering-javascript-typescriptv1.0.0
- engineering-jvmv1.0.0
- engineering-mobilev1.0.0
- engineering-other-languagesv1.0.0
- engineering-pythonv1.0.0
- engineering-systems-languagesv1.0.0
- engineering-testingv1.0.0
- marketing-content-socialv1.0.0
- marketing-growth-adsv1.0.0
- marketing-seov1.0.0
- productivity-automation-personalv1.0.0
- productivity-documents-officev1.0.0
- productivity-thinking-planningv1.0.0