Replace an existing object with a new version of it.

        :param unicode collection_name: The name of the collection in which to
            replace an object.

        :param IObject old: A description of the object being replaced.

        :param IObject new: A description of the object to take the place of
            ``old``.

        :return _KubernetesState: A new state based on the current state but
            also containing ``obj``.

def replace(self, collection_name, old, new):
        """
        Replace an existing object with a new version of it.

        :param unicode collection_name: The name of the collection in which to
            replace an object.

        :param IObject old: A description of the object being replaced.

        :param IObject new: A description of the object to take the place of
            ``old``.

        :return _KubernetesState: A new state based on the current state but
            also containing ``obj``.
        """
        self.agency.before_replace(self, old, new)
        updated = self.transform(
            [collection_name],
            lambda c: c.replace(old, new),
        )
        return updated