+ "NOTE: If onfence-poweroff is set, the agent won't be able to power on the node again, it will have to be powered on manually or with other automation."
+ ),
+ "vendorurl": "http://www.amazon.com"
+ }
+ show_docs(options, docs)
+
+ if "--onfence-poweroff" not in options and options.get("--action", "") == "reboot":
+The fence_aws_vpc_net agent is a network and power fencing agent for AWS VPC that operates by manipulating security groups. This document outlines the design and architecture of the agent.
+
+## Class Diagram
+
+```mermaid
+classDiagram
+ class FenceAWSVPCNet {
+ -logger: Logger
+ -conn: boto3.resource
+ -options: dict
+ +main()
+ +define_new_opts()
+ +process_input()
+ +check_input()
+ }
+
+ class AWSConnection {
+ -region: str
+ -access_key: str
+ -secret_key: str
+ +establish_connection()
+ +validate_credentials()
+ }
+
+ class SecurityGroupManager {
+ +modify_security_groups()
+ +create_backup_tag()
+ +restore_security_groups()
+ -validate_sg_changes()
+ }
+
+ class InstanceManager {
+ +get_instance_details()
+ +shutdown_instance()
+ +get_power_status()
+ +set_power_status()
+ -validate_instance_state()
+ }
+
+ class TagManager {
+ +set_lastfence_tag()
+ +get_backup_tags()
+ +cleanup_tags()
+ -validate_tag_operations()
+ }
+
+ FenceAWSVPCNet --> AWSConnection
+ FenceAWSVPCNet --> SecurityGroupManager
+ FenceAWSVPCNet --> InstanceManager
+ SecurityGroupManager --> TagManager
+ InstanceManager --> TagManager
+
+```
+
+## Sequence Diagrams
+
+### Fence Operation (Power Off)
+
+```mermaid
+sequenceDiagram
+ participant Client
+ participant FenceAgent
+ participant AWS
+ participant SecurityGroups
+ participant Tags
+
+ Client->>FenceAgent: Execute fence operation
+ FenceAgent->>AWS: Validate AWS credentials
+ AWS-->>FenceAgent: Credentials valid
+
+ FenceAgent->>AWS: Get instance details
+ AWS-->>FenceAgent: Instance details
+
+ alt Instance is running
+ FenceAgent->>SecurityGroups: Backup current security groups
+ SecurityGroups-->>FenceAgent: Backup created
+
+ FenceAgent->>Tags: Create lastfence tag
+ Tags-->>FenceAgent: Tag created
+
+ FenceAgent->>SecurityGroups: Modify security groups
+ SecurityGroups-->>FenceAgent: Groups modified
+
+ opt onfence-poweroff enabled
+ FenceAgent->>AWS: Initiate shutdown
+ AWS-->>FenceAgent: Shutdown initiated
+ end
+
+ FenceAgent-->>Client: Success
+ else Instance not running
+ FenceAgent-->>Client: Fail - Instance not running
+ end
+```
+
+### Unfence Operation (Power On)
+
+```mermaid
+sequenceDiagram
+ participant Client
+ participant FenceAgent
+ participant AWS
+ participant SecurityGroups
+ participant Tags
+
+ Client->>FenceAgent: Execute unfence operation
+ FenceAgent->>AWS: Validate AWS credentials
+ AWS-->>FenceAgent: Credentials valid
+
+ FenceAgent->>Tags: Get lastfence tag
+ Tags-->>FenceAgent: Lastfence tag
+
+ FenceAgent->>Tags: Get backup tags
+ Tags-->>FenceAgent: Backup tags
+
+ alt Valid backup found
+ FenceAgent->>SecurityGroups: Restore original security groups
+ SecurityGroups-->>FenceAgent: Groups restored
+
+ FenceAgent->>Tags: Cleanup backup tags
+ Tags-->>FenceAgent: Tags cleaned
+
+ FenceAgent-->>Client: Success
+ else No valid backup
+ FenceAgent-->>Client: Fail - No valid backup found
+ end
+```
+
+## Component Details
+
+### 1. Main Controller (FenceAWSVPCNet)
+- **Purpose**: Main entry point and orchestration
+- **Key Responsibilities**:
+ - Process command line options
+ - Initialize AWS connection
+ - Execute fence operations
+ - Handle logging and errors
+
+### 2. AWS Connection Manager
+- **Purpose**: Handle AWS connectivity
+- **Key Responsibilities**:
+ - Establish and maintain AWS connection
+ - Handle credentials and regions
+ - Manage API retries and timeouts
+
+### 3. Security Group Manager
+- **Purpose**: Manage security group operations
+- **Key Responsibilities**:
+ - Modify security groups
+ - Create backups of security group configurations
+ - Restore security groups from backups
+ - Validate security group changes
+
+### 4. Instance Manager
+- **Purpose**: Handle EC2 instance operations
+- **Key Responsibilities**:
+ - Get instance details and status
+ - Handle instance power operations
+ - Validate instance states
+ - Manage self-fencing prevention
+
+### 5. Tag Manager
+- **Purpose**: Manage AWS resource tagging
+- **Key Responsibilities**:
+ - Create and manage backup tags
+ - Handle lastfence tags
+ - Clean up tags after operations
+ - Validate tag operations
+
+## Success and Failure Paths
+
+### Success Paths
+
+1. **Normal Fence Operation**
+```
+Start
+├── Validate AWS credentials
+├── Check instance is running
+├── Backup security groups
+├── Create lastfence tag
+├── Modify security groups
+├── [Optional] Shutdown instance
+└── Success
+```
+
+2. **Normal Unfence Operation**
+```
+Start
+├── Validate AWS credentials
+├── Find lastfence tag
+├── Find backup tags
+├── Restore security groups
+├── Clean up tags
+└── Success
+```
+
+### Failure Paths
+
+1. **Authentication Failures**
+```
+Start
+├── Invalid AWS credentials
+└── Fail with auth error
+```
+
+2. **Instance State Failures**
+```
+Start
+├── Instance not in required state
+└── Fail with state error
+```
+
+3. **Security Group Operation Failures**
+```
+Start
+├── Backup creation fails
+│ └── Fail with backup error
+├── Security group modification fails
+│ └── Fail with modification error
+└── Restoration fails
+ └── Fail with restore error
+```
+
+4. **Tag Operation Failures**
+```
+Start
+├── Tag creation fails
+│ └── Fail with tag error
+├── Tag retrieval fails
+│ └── Fail with retrieval error
+└── Tag cleanup fails
+ └── Warning (non-fatal)
+```
+
+## Error Handling
+
+### Error Categories
+1. **AWS API Errors**
+ - ConnectionError
+ - ClientError
+ - EndpointConnectionError
+ - NoRegionError
+
+2. **Validation Errors**
+ - Invalid parameters
+ - Missing required options
+ - Invalid security group configurations
+
+3. **State Errors**
+ - Instance state conflicts
+ - Security group conflicts
+ - Self-fencing detection
+
+### Error Recovery
+- Automatic retries for transient AWS API errors
+- Rollback of security group changes on partial failures
+- Preservation of backup tags for manual recovery
+- Detailed logging for troubleshooting
+
+## Configuration Options
+
+### Required Options
+- `--plug`: AWS Instance ID
+- AWS credentials (via options or environment)
+
+### Optional Options
+- `--region`: AWS region
+- `--secg`: Security groups to remove
+- `--skip-race-check`: Skip self-fencing check
+- `--invert-sg-removal`: Invert security group removal
+- `--unfence-ignore-restore`: Skip restore on unfence
+<resource-agent name="fence_aws_vpc_net" shortdesc="Fence agent for AWS (Amazon Web Services) Net" >
+<longdesc>fence_aws_vpc is a Network and Power Fencing agent for AWS VPC that works by manipulating security groups. It uses the boto3 library to connect to AWS.
+
+boto3 can be configured with AWS CLI or by creating ~/.aws/credentials.
+For instructions see: https://boto3.readthedocs.io/en/latest/guide/quickstart.html#configuration NOTE: If onfence-poweroff is set, the agent won't be able to power on the node again, it will have to be powered on manually or with other automation.</longdesc>
+ <shortdesc lang="en">Level of debugging detail in output. Defaults to the number of --verbose flags specified on the command line, or to 1 if verbose=1 in a stonith device configuration (i.e., on stdin).</shortdesc>