Skip to content

Commit 2257f39

Browse files
sbaidachniCopilotmawasile
authored
Custom script execution technical details and a decision matrix (#234)
* initial document * Update docs/design/execute_custom_code.md Co-authored-by: Copilot <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Copilot <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * Update docs/design/execute_custom_code.md Co-authored-by: Mateusz Wasilewski <[email protected]> * infor extracted into ADR * address comments --------- Co-authored-by: Copilot <[email protected]> Co-authored-by: Mateusz Wasilewski <[email protected]>
1 parent e7b88aa commit 2257f39

File tree

2 files changed

+134
-0
lines changed

2 files changed

+134
-0
lines changed

‎decision-log/003-vnet-resource-configuration-strategy.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# ADR 003: Resource Configuration within VNET
2+
3+
**Date:** 2025-08-11
4+
**Status:** Approved
5+
6+
## Context
7+
When deploying Azure infrastructure that includes a Virtual Network (VNET), we need to execute custom scripts to configure resources that are isolated from public networks. For example, Azure AI Search deployed without public access requires Python scripts to create indexes, indexers, and skillsets. The deployment orchestration (GitHub Actions) runs outside the created VNET and cannot directly access these private resources.
8+
9+
Key requirements:
10+
11+
- Execute Python scripts for Azure AI Search configuration within VNET
12+
- Maintain security by keeping resources within VNET boundaries
13+
- Support both local testing and CI/CD deployment scenarios
14+
- Minimize infrastructure complexity while maintaining flexibility
15+
16+
## Decision
17+
18+
We will use **Azure Deployment Scripts** as the primary method for executing custom code within VNET during infrastructure deployment.
19+
20+
## Rationale
21+
22+
Azure Deployment Scripts provide the optimal balance of simplicity, security, and functionality for our use case:
23+
24+
**Advantages:**
25+
26+
- Simple implementation requiring minimal infrastructure components
27+
- Compatible with local testing and CI/CD workflows
28+
- No need for GitHub private runners or complex networking between GitHub and Azure
29+
- Automatic cleanup of temporary resources after execution
30+
- Built-in support for Python 3, PowerShell and Azure CLI
31+
- Fits within standard organizational security policies
32+
33+
**Trade-offs Accepted:**
34+
35+
- No custom images are supported, but required components can be installed using bash scripts
36+
- Requires git clone for multi-file Python projects or access to a storage with pre-uploaded code
37+
- Less suitable for complex operational processes requiring persistent infrastructure
38+
- End-to-end testing leverages the Copilot Studio public endpoint; however, for scenarios requiring direct access to the data plane or private network, this approach can be complemented by using GitHub self-hosted runners within the VNET.
39+
40+
**Alternatives Considered:**
41+
42+
- VM Custom Script Extensions: More complex infrastructure, requires ongoing VM management
43+
- Azure Container Applications as a GitHub selh-hosted runner: Higher complexity, better for scalable/persistent scenarios
44+
45+
## Implementation Details
46+
47+
The following actions should be taken to implement the selected approach:
48+
49+
- Use AzAPI provider (~>2.0) for latest Azure Deployment Script features
50+
- Configure Azure Deployment Script to use Azure Container Instance (ACI) within dedicated subnet with proper delegation
51+
- Utilize storage account with network rules for deployment script state management
52+
- Implement user-assigned managed identity with minimal required permissions
53+
- Use git clone approach or a dedicated storage account for retrieving Python scripts from repository
54+
55+
## Related Decisions
56+
57+
- [ADR 004: GitHub Runner Strategy](004-github-runner-strategy.md) - GitHub runner approach for broader automation needs

‎decision-log/004-github-runner-strategy.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# ADR 004: GitHub Runner Strategy
2+
3+
**Date:** 2025-08-11
4+
**Status:** Approved
5+
6+
## Context
7+
8+
Our project requires GitHub Actions automation for CI/CD workflows that need access to Azure VNET resources for testing, validation, and operational tasks beyond initial deployment. Additionally, it is important to keep Terraform state files secure by avoiding the use of public endpoints for state storage and access. Since GitHub-hosted runners cannot access private VNET resources, a self-hosted runner solution is required.
9+
10+
Key requirements:
11+
12+
- Execute GitHub workflows with access to VNET resources
13+
- Keep Terraform state files secure by restricting access to state files
14+
- Support multiple concurrent workflows for team collaboration
15+
- Minimize operational overhead and infrastructure costs
16+
- Provide flexibility for various programming languages and tools
17+
- Align with organizational security and automation policies
18+
19+
## Decision
20+
21+
We will use GitHub-hosted runners and Azure Deployment Scripts as the default for standard operations, recognizing that not all users of the template can set up a self-hosted runner. However, we strongly recommend self-hosted runners as the preferred approach. Self-hosted runners are required for scenarios that need VNET access or specialized environments. When self-hosted runners are necessary, we recommend Azure Container Apps (ACA) as the primary option.
22+
23+
## Rationale
24+
25+
Azure Container Applications provide the best balance of scalability, cost-efficiency, and operational simplicity:
26+
27+
**Advantages:**
28+
29+
- **Scalability**: Automatically scales based on workflow demand, supporting concurrent executions
30+
- **Cost Efficiency**: Resources consumed only during workflow execution
31+
- **Technology Flexibility**: Supports various programming languages and tools through custom container images
32+
- **Reduced Maintenance**: Serverless model eliminates VM management overhead
33+
- **Team Collaboration**: Multiple developers can execute workflows simultaneously without conflicts
34+
35+
**Trade-offs Accepted:**
36+
37+
- **Initial Complexity**: More complex initial setup compared to VM-based approach
38+
- **Image Management**: Requires workflow for updating container images
39+
- **Docker Limitations**: Cannot use Docker-in-Docker, must use ACR tools for container builds
40+
41+
**Alternatives Considered:**
42+
43+
- **VM-based runners**: Simpler setup but poor scalability, manual VM management required
44+
- **Azure Kubernetes Service (AKS)**: Enterprise-grade scalability, advanced orchestration capabilities. At the same time it has high complexity, significant operational overhead, requires Kubernetes expertise
45+
46+
## Self-Hosted Runner Comparison
47+
48+
| Aspect | ACA | VM | AKS |
49+
|--------|-----|----|----|
50+
| Scalability | Excellent | Limited | Excellent |
51+
| Setup Complexity | Medium | Low | High |
52+
| Resource Efficiency | Excellent | Poor | Good |
53+
| Maintenance Overhead | Low | Medium | High |
54+
| Technology Support | Container-based | Full | Container-based |
55+
| Cost Model | Pay-per-use | Always-on | Pay-per-use |
56+
57+
## Implementation Details
58+
59+
The following actions should be taken to implement the selected approach:
60+
61+
- Teams start with GitHub-hosted runners for standard workflows
62+
- Self-hosted runner infrastructure deployed only when VNET access is required
63+
- ACA-based runners require container image management workflows
64+
- VM-based runners suitable for testing and simple use cases with manual intervention
65+
- Teams must evaluate organizational policies regarding self-hosted runners
66+
67+
Implementation Plan:
68+
69+
- Deploy ACR and basic ACA infrastructure within VNET
70+
- Create initial GitHub runner container image with essential tools
71+
- Implement ACR Task for automated image building and deployment
72+
- Configure GitHub repository to use self-hosted runners
73+
- Create image update workflow using ACA runners
74+
75+
## Related Decisions
76+
77+
- [ADR 003: VNET Resource Configuration Strategy](003-vnet-resource-configuration-strategy.md) - Azure Deployment Scripts for deployment tasks

0 commit comments

Comments
 (0)