Skip to content

Commit 405fa9d

Browse files
Copilotrbtr
Copilot
and
rbtr
committed
Add documentation for Windows service support
- Add comprehensive Windows service documentation (cns/doc/windows-service.md) - Create CNS README with Windows service information - Include installation, configuration, and troubleshooting guides - Add command-line reference and examples Co-authored-by: rbtr <[email protected]>
1 parent 8ab9a1a commit 405fa9d

File tree

2 files changed

+310
-0
lines changed

2 files changed

+310
-0
lines changed

‎cns/README.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Azure Container Networking Service (CNS)
2+
3+
Azure Container Networking Service (CNS) is a service that provides container networking capabilities for Azure environments. It manages IP address allocation, network policy enforcement, and container network configuration.
4+
5+
## Features
6+
7+
- **IP Address Management (IPAM)**: Dynamic allocation and management of IP addresses for containers
8+
- **Network Container Management**: Creation and management of network containers
9+
- **Multi-tenancy Support**: Isolation and management of network resources across multiple tenants
10+
- **Kubernetes Integration**: Native integration with Kubernetes for CNI plugin support
11+
- **Windows Service Support**: Run CNS as a Windows service for automatic startup and recovery
12+
13+
## Running CNS
14+
15+
### Linux
16+
17+
On Linux systems, CNS is typically run as a daemon or managed by systemd:
18+
19+
```bash
20+
./azure-cns [OPTIONS]
21+
```
22+
23+
### Windows
24+
25+
On Windows systems, CNS can be run as a standalone executable or registered as a Windows service.
26+
27+
#### As a Windows Service
28+
29+
CNS can be installed as a Windows service to enable automatic startup and recovery:
30+
31+
```powershell
32+
# Install the service
33+
azure-cns.exe --service install
34+
35+
# Start the service
36+
net start azure-cns
37+
```
38+
39+
See [Windows Service Documentation](doc/windows-service.md) for detailed information on Windows service features and management.
40+
41+
#### As a Standalone Executable
42+
43+
You can also run CNS directly:
44+
45+
```powershell
46+
azure-cns.exe [OPTIONS]
47+
```
48+
49+
## Configuration
50+
51+
CNS can be configured using:
52+
- Command-line arguments
53+
- Configuration file (JSON format)
54+
- Environment variables
55+
56+
### Common Command-Line Options
57+
58+
```
59+
-e, --environment= Set the operating environment {azure,mas,fileIpam}
60+
-l, --log-level=info Set the logging level {info,debug}
61+
-t, --log-target=logfile Set the logging target {syslog,stderr,logfile,stdout,stdoutfile}
62+
-c, --cns-url= Set the URL for CNS to listen on
63+
-p, --cns-port= Set the URL port for CNS to listen on
64+
-cp, --config-path= Path to cns config file
65+
-v, --version Print version information
66+
-s, --service= Windows service action: install, uninstall, or run as service (Windows only)
67+
```
68+
69+
For a complete list of options, run:
70+
71+
```bash
72+
azure-cns --help
73+
```
74+
75+
## Building CNS
76+
77+
To build CNS from source:
78+
79+
```bash
80+
cd cns/service
81+
go build -o azure-cns
82+
```
83+
84+
Or use the Makefile from the repository root:
85+
86+
```bash
87+
make azure-cns-binary
88+
```
89+
90+
## Documentation
91+
92+
- [Windows Service Documentation](doc/windows-service.md) - Detailed guide for running CNS as a Windows service
93+
- [Swift V2 Features](../docs/feature/swift-v2/cns.md) - Swift V2 networking features
94+
- [Async Delete](../docs/feature/async-delete/cns.md) - Asynchronous pod deletion
95+
96+
## API Documentation
97+
98+
CNS exposes a REST API for container network management. The API documentation can be found in the [swagger.yaml](swagger.yaml) file.
99+
100+
## Development
101+
102+
### Testing
103+
104+
Run tests using:
105+
106+
```bash
107+
cd cns
108+
go test ./...
109+
```
110+
111+
### Linting
112+
113+
Format and lint the code:
114+
115+
```bash
116+
make fmt
117+
make lint
118+
```
119+
120+
## Support
121+
122+
For issues and questions:
123+
- Create an issue in the [GitHub repository](https://github.com/Azure/azure-container-networking/issues)
124+
- Review existing [documentation](../docs/)
125+
126+
## License
127+
128+
This project is licensed under the MIT License - see the [LICENSE](../LICENSE) file for details.

‎cns/doc/windows-service.md‎

Lines changed: 182 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,182 @@
1+
# Azure CNS Windows Service
2+
3+
Azure CNS (Container Networking Service) can be registered and run as a Windows service, enabling automatic startup on system boot and automatic restart on failure.
4+
5+
## Features
6+
7+
- **Automatic Startup**: CNS starts automatically when the Windows system boots
8+
- **Automatic Recovery**: Service automatically restarts on failure (with 5-second delays)
9+
- **Event Logging**: Service lifecycle events are logged to Windows Event Log
10+
- **Service Management**: Easy installation and uninstallation via command-line flags
11+
12+
## Installation
13+
14+
To install Azure CNS as a Windows service, run the following command with administrator privileges:
15+
16+
```powershell
17+
azure-cns.exe --service install
18+
```
19+
20+
or using the short form:
21+
22+
```powershell
23+
azure-cns.exe -s install
24+
```
25+
26+
This will:
27+
1. Register the service with the Windows Service Control Manager
28+
2. Configure the service to start automatically on system boot
29+
3. Set up automatic restart on failure
30+
4. Create an event log source for CNS
31+
32+
After installation, you can start the service using:
33+
34+
```powershell
35+
net start azure-cns
36+
```
37+
38+
or via the Services management console (`services.msc`).
39+
40+
## Uninstallation
41+
42+
To uninstall the Azure CNS Windows service, run the following command with administrator privileges:
43+
44+
```powershell
45+
azure-cns.exe --service uninstall
46+
```
47+
48+
or using the short form:
49+
50+
```powershell
51+
azure-cns.exe -s uninstall
52+
```
53+
54+
This will:
55+
1. Stop the service if it's running
56+
2. Remove the service from the Windows Service Control Manager
57+
3. Remove the event log source
58+
59+
## Service Configuration
60+
61+
The service is registered with the following configuration:
62+
63+
- **Service Name**: `azure-cns`
64+
- **Display Name**: `Azure Container Networking Service`
65+
- **Description**: `Provides container networking services for Azure`
66+
- **Start Type**: Automatic
67+
- **Service Account**: LocalSystem
68+
- **Recovery Actions**:
69+
- First failure: Restart the service after 5 seconds
70+
- Second failure: Restart the service after 5 seconds
71+
- Subsequent failures: Restart the service after 5 seconds
72+
- Reset failure count after: 24 hours
73+
74+
## Running as a Service
75+
76+
Once installed, the service will automatically detect when it's being started by the Windows Service Control Manager and will run in service mode. No additional command-line flags are needed when the service is started by Windows.
77+
78+
For testing purposes, you can explicitly run in service mode using:
79+
80+
```powershell
81+
azure-cns.exe --service run
82+
```
83+
84+
## Event Logging
85+
86+
Service lifecycle events are logged to the Windows Event Log under the Application log with the source name `azure-cns`. You can view these logs using:
87+
88+
```powershell
89+
Get-EventLog -LogName Application -Source azure-cns -Newest 20
90+
```
91+
92+
or via the Event Viewer (`eventvwr.msc`).
93+
94+
## Troubleshooting
95+
96+
### Service fails to install
97+
98+
Ensure you are running the command prompt or PowerShell as Administrator. The service installation requires elevated privileges.
99+
100+
### Service fails to start
101+
102+
1. Check the Windows Event Log for error messages:
103+
```powershell
104+
Get-EventLog -LogName Application -Source azure-cns -Newest 10
105+
```
106+
107+
2. Verify that all required configuration files are present
108+
109+
3. Check that the executable path is correct
110+
111+
4. Try running the executable directly (not as a service) to identify any configuration issues:
112+
```powershell
113+
azure-cns.exe
114+
```
115+
116+
### Service doesn't restart on failure
117+
118+
The service is configured to restart automatically up to 3 times within a 24-hour period. If the service continues to fail, it will remain stopped. Check the Event Log for the root cause and fix the underlying issue before restarting the service.
119+
120+
## Command-Line Reference
121+
122+
```
123+
-s, --service= Windows service action: install, uninstall, or run as service {install,uninstall,run,}
124+
```
125+
126+
**Available actions:**
127+
- `install`: Install Azure CNS as a Windows service
128+
- `uninstall`: Uninstall the Azure CNS Windows service
129+
- `run`: Explicitly run in service mode (typically not needed)
130+
- ` ` (empty): Normal execution mode (auto-detects if running as service)
131+
132+
## Examples
133+
134+
### Install and start the service
135+
136+
```powershell
137+
# Install the service
138+
azure-cns.exe --service install
139+
140+
# Start the service
141+
net start azure-cns
142+
143+
# Verify the service is running
144+
Get-Service azure-cns
145+
```
146+
147+
### Stop and uninstall the service
148+
149+
```powershell
150+
# Stop the service
151+
net stop azure-cns
152+
153+
# Uninstall the service
154+
azure-cns.exe --service uninstall
155+
```
156+
157+
### Check service status
158+
159+
```powershell
160+
# Using PowerShell
161+
Get-Service azure-cns
162+
163+
# Using sc.exe
164+
sc query azure-cns
165+
```
166+
167+
### View service logs
168+
169+
```powershell
170+
# View recent events
171+
Get-EventLog -LogName Application -Source azure-cns -Newest 20 | Format-Table -AutoSize
172+
173+
# View only errors
174+
Get-EventLog -LogName Application -Source azure-cns -EntryType Error -Newest 10
175+
```
176+
177+
## Notes
178+
179+
- This feature is only available on Windows platforms. On Linux, use systemd or other init systems to manage the service.
180+
- The service must be installed with administrator privileges.
181+
- The service runs under the LocalSystem account, which has high privileges. Ensure the executable and configuration files are properly secured.
182+
- Service configuration (command-line flags, config files) should be set via the Windows Registry or by using command-line parameters in the service's "Image Path" in the service properties.

0 commit comments

Comments
 (0)