When we talk about "configuration management," we're really talking about idempotency. If you run your tool once, it makes the change. If you run it ten more times, it should do absolutely nothing because the system is already in the desired state. Building this in Go is a great exercise because it forces you to think about interfaces and the boundary between your code and the operating system.

How should I structure the logic so I can add different types of resources, like files and packages, without rewriting the main loop?

If you hardcode logic for "files" and "users" in your main loop, you'll be fighting your own codebase by the time you add the fifth resource type. I always recommend using an interface. I call it the Resource interface. Every single thing your tool manages—whether it's a symlink, a systemd service, or a config file—should satisfy this interface.

type Resource interface {
    Check() (bool, error) // Returns true if the system is already in the desired state
    Apply() error         // Performs the action to reach the desired state
    Name() string         // For logging purposes
}

Now, your main execution engine doesn't need to know what it's managing. It just iterates over a slice of Resource objects, calls Check(), and if that returns false, it calls Apply(). This keeps your "engine" clean and your "providers" isolated.

What's the actual trick to making the tool idempotent?

The "trick" is that Check() must be an honest reflection of the current state, not a guess. For example, if you're managing a file's permissions, don't just check if the file exists. You need to check the actual mode bits.

Here is a simplified version of how I'd implement a FileResource. Notice how Check does the heavy lifting of validation before Apply ever touches the disk:

type FileResource struct {
    Path    string
    Content string
}

func (f *FileResource) Check() (bool, error) {
    data, err := os.ReadFile(f.Path)
    if err != nil {
        if os.IsNotExist(err) {
            return false, nil // File missing, definitely not in desired state
        }
        return false, err
    }
    return string(data) == f.Content, nil
}

func (f *FileResource) Apply() error {
    return os.WriteFile(f.Path, []byte(f.Content), 0644)
}

func (f *FileResource) Name() string {
    return "File: " + f.Path
}

How do I handle the actual execution of system commands without making the code a mess?

Eventually, you'll need to do things Go's standard library can't do easily, like calling apt-get or systemctl. The temptation is to use fmt.Sprintf to build a shell string and pass it to a shell. Don't do that. It's a security nightmare and a quoting headache.

Use os/exec and pass arguments as a slice. I usually wrap this in a helper method within my resource provider. If I'm building a PackageResource, it looks something like this:

func (p *PackageResource) Apply() error {
    // We explicitly avoid "sh -c" to prevent shell injection
    cmd := exec.Command("apt-get", "install", "-y", p.PackageName)
    if err := cmd.Run(); err != nil {
        return fmt.Errorf("failed to install %s: %w", p.PackageName, err)
    }
    return nil
}

I'll be honest: debugging os/exec can be frustrating because cmd.Run() hides the output. When you're developing these providers, I suggest capturing cmd.CombinedOutput() and logging it if an error occurs. It'll save you hours of wondering why a package failed to install.

📋 Practical Task

Build a "System User Enforcer" Resource

Your task is to implement a new resource for your configuration management tool that ensures a specific system user exists. You should not use a third-party library; stick to the os/exec package.

• Define a UserResource struct that holds the Username and the Shell (e.g., /bin/bash).
• Implement the Check() method. It should return true if the user exists and is using the specified shell. (Hint: You can check this by running getent passwd [username] and parsing the output).
• Implement the Apply() method. It should create the user using the useradd command with the -s flag for the shell.
• Implement the Name() method returning a string like "User: username".

Testing your code: Create a slice of Resource interfaces containing your UserResource, then write a loop that calls Check() and Apply(). Run it twice; the second time, the Apply() method should never be triggered.