0
# Configuration
1

2
Pulumi's configuration system provides secure management of settings and secrets across different environments and stacks. Configuration values can be plain text or encrypted secrets, with type-safe access methods.
3

4
## Core Configuration Class
5

6
```typescript { .api }
7
class Config {
8
  /**
9
   * Create a configuration bag for the specified name (defaults to current project)
10
   */
11
  constructor(name?: string);
12

13
  // Plain configuration methods
14
  get<K extends string = string>(key: string, opts?: StringConfigOptions<K>): K | undefined;
15
  require<K extends string = string>(key: string, opts?: StringConfigOptions<K>): K;
16
  getBoolean(key: string): boolean | undefined;
17
  requireBoolean(key: string): boolean;
18
  getNumber(key: string, opts?: NumberConfigOptions): number | undefined;
19
  requireNumber(key: string, opts?: NumberConfigOptions): number;
20
  getObject<T>(key: string): T | undefined;
21
  requireObject<T>(key: string): T;
22

23
  // Secret configuration methods
24
  getSecret<K extends string = string>(key: string, opts?: StringConfigOptions<K>): Output<K | undefined>;
25
  requireSecret<K extends string = string>(key: string, opts?: StringConfigOptions<K>): Output<K>;
26
  getSecretBoolean(key: string): Output<boolean | undefined>;
27
  requireSecretBoolean(key: string): Output<boolean>;
28
  getSecretNumber(key: string, opts?: NumberConfigOptions): Output<number | undefined>;
29
  requireSecretNumber(key: string, opts?: NumberConfigOptions): Output<number>;
30
  getSecretObject<T>(key: string): Output<T | undefined>;
31
  requireSecretObject<T>(key: string): Output<T>;
32

33
  readonly name: string;
34
}
35
```
36

37
## Configuration Options
38

39
```typescript { .api }
40
interface StringConfigOptions<K> {
41
  allowedValues?: K[];
42
}
43

44
interface NumberConfigOptions {
45
  min?: number;
46
  max?: number;
47
}
48
```
49

50
## Usage Examples
51

52
### Basic Configuration
53

54
```typescript
55
import { Config } from "@pulumi/pulumi";
56

57
const config = new Config();
58

59
// Get optional string value
60
const environment = config.get("environment") || "development";
61

62
// Get required string value
63
const region = config.require("region");
64

65
// Get typed values
66
const instanceCount = config.getNumber("instanceCount") || 1;
67
const enableFeature = config.getBoolean("enableFeature") || false;
68

69
// Get complex objects
70
interface DatabaseConfig {
71
  host: string;
72
  port: number;
73
  database: string;
74
}
75

76
const dbConfig = config.requireObject<DatabaseConfig>("database");
77
```
78

79
### Secret Configuration
80

81
```typescript
82
import { Config } from "@pulumi/pulumi";
83

84
const config = new Config();
85

86
// Get secret values (returns Output<T>)
87
const apiKey = config.requireSecret("apiKey");
88
const dbPassword = config.getSecret("dbPassword");
89

90
// Use secrets in resources
91
const database = new aws.rds.Instance("db", {
92
  username: "admin",
93
  password: dbPassword, // Output<string | undefined>
94
  // ... other properties
95
});
96
```
97

98
### Project-Specific Configuration
99

100
```typescript
101
import { Config } from "@pulumi/pulumi";
102

103
// Default config uses current project name
104
const config = new Config();
105

106
// Named config for specific component
107
const redisConfig = new Config("redis");
108
const cacheSize = redisConfig.getNumber("cacheSize") || 128;
109

110
// Cross-project config
111
const sharedConfig = new Config("shared-infra");
112
const vpcId = sharedConfig.require("vpcId");
113
```
114

115
### Constrained Configuration
116

117
```typescript
118
import { Config } from "@pulumi/pulumi";
119

120
const config = new Config();
121

122
// String with allowed values
123
const size = config.get("size", {
124
  allowedValues: ["small", "medium", "large"]
125
}) || "medium";
126

127
// Number with constraints
128
const port = config.getNumber("port", {
129
  min: 1024,
130
  max: 65535
131
}) || 8080;
132
```
133

134
### Configuration Validation Patterns
135

136
```typescript
137
import { Config } from "@pulumi/pulumi";
138

139
const config = new Config();
140

141
// Validate required configuration at program start
142
function validateConfig() {
143
  const required = ["region", "environment"];
144
  const missing = required.filter(key => !config.get(key));
145
  
146
  if (missing.length > 0) {
147
    throw new Error(`Missing required configuration: ${missing.join(", ")}`);
148
  }
149
}
150

151
validateConfig();
152

153
// Environment-specific defaults
154
function getInstanceType(): string {
155
  const env = config.require("environment");
156
  const instanceType = config.get("instanceType");
157
  
158
  if (instanceType) {
159
    return instanceType;
160
  }
161
  
162
  // Environment-based defaults
163
  switch (env) {
164
    case "production":
165
      return "t3.large";
166
    case "staging":
167
      return "t3.medium";
168
    default:
169
      return "t3.micro";
170
  }
171
}
172
```
173

174
## Configuration Sources
175

176
Configuration values are resolved from multiple sources in this order:
177

178
1. Environment variables (prefixed with `PULUMI_CONFIG_`)
179
2. Stack configuration file (`Pulumi.<stack>.yaml`)
180
3. Project configuration file (`Pulumi.yaml`)
181
4. Default values in code
182

183
## Best Practices
184

185
- Use `require()` methods for mandatory configuration
186
- Provide sensible defaults with `get()` methods
187
- Use secrets for sensitive data (passwords, API keys, tokens)
188
- Validate configuration early in your program
189
- Use typed configuration objects for complex settings
190
- Document required configuration in your project README